Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

5.1 KiB

Raw Blame History

name, description

name	description
nuxt-layers	Extending Nuxt applications with layers for code sharing and reusability

Nuxt Layers

Layers allow sharing and reusing partial Nuxt applications across projects. They can include components, composables, pages, layouts, and configuration.

Using Layers

From npm Package

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@my-org/base-layer', '@nuxtjs/ui-layer'],
});

From Git Repository

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    'github:username/repo',
    'github:username/repo/base', // Subdirectory
    'github:username/repo#v1.0', // Specific tag
    'github:username/repo#dev', // Branch
    'gitlab:username/repo',
    'bitbucket:username/repo',
  ],
});

From Local Directory

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['../base-layer', './layers/shared'],
});

Auto-scanned Layers

Place in layers/ directory for automatic discovery:

my-app/
├── layers/
│   ├── base/
│   │   └── nuxt.config.ts
│   └── ui/
│       └── nuxt.config.ts
└── nuxt.config.ts

Creating a Layer

Minimal layer structure:

my-layer/
├── nuxt.config.ts       # Required
├── app/
│   ├── components/      # Auto-merged
│   ├── composables/     # Auto-merged
│   ├── layouts/         # Auto-merged
│   ├── middleware/      # Auto-merged
│   ├── pages/           # Auto-merged
│   ├── plugins/         # Auto-merged
│   └── app.config.ts    # Merged
├── server/              # Auto-merged
└── package.json

Layer nuxt.config.ts

// my-layer/nuxt.config.ts
export default defineNuxtConfig({
  // Layer configuration
  app: {
    head: {
      title: 'My Layer App',
    },
  },
  // Shared modules
  modules: ['@nuxt/ui'],
});

Layer Components

<!-- my-layer/app/components/BaseButton.vue -->
<template>
  <button class="base-btn">
    <slot />
  </button>
</template>

Use in consuming project:

<template>
  <BaseButton>Click me</BaseButton>
</template>

Layer Composables

// my-layer/app/composables/useTheme.ts
export function useTheme() {
  const isDark = useState('theme-dark', () => false);
  const toggle = () => (isDark.value = !isDark.value);
  return { isDark, toggle };
}

Layer Priority

Override order (highest to lowest):

Your project files
Auto-scanned layers (alphabetically, Z > A)
extends array (first > last)

Control order with prefixes:

layers/
├── 1.base/      # Lower priority
└── 2.theme/     # Higher priority

Layer Aliases

Access layer files:

// Auto-scanned layers get aliases
import Component from '#layers/base/components/Component.vue';

Named aliases:

// my-layer/nuxt.config.ts
export default defineNuxtConfig({
  $meta: {
    name: 'my-layer',
  },
});

// In consuming project
import { something } from '#layers/my-layer/utils';

Publishing Layers

As npm Package

{
  "name": "my-nuxt-layer",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {
    "@nuxt/ui": "^2.0.0"
  },
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}

Private Layers

For private git repos:

export GIGET_AUTH=<github-token>

Layer Best Practices

Use Resolved Paths

// my-layer/nuxt.config.ts
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const currentDir = dirname(fileURLToPath(import.meta.url));

export default defineNuxtConfig({
  css: [join(currentDir, './assets/main.css')],
});

Install Dependencies

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [['github:user/layer', { install: true }]],
});

Disable Layer Modules

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['./base-layer'],
  // Disable modules from layer
  image: false, // Disables @nuxt/image
  pinia: false, // Disables @pinia/nuxt
});

Starter Template

Create a new layer:

npx nuxi init --template layer my-layer

Example: Theme Layer

theme-layer/
├── nuxt.config.ts
├── app/
│   ├── app.config.ts
│   ├── components/
│   │   ├── ThemeButton.vue
│   │   └── ThemeCard.vue
│   ├── composables/
│   │   └── useTheme.ts
│   └── assets/
│       └── theme.css
└── package.json

// theme-layer/nuxt.config.ts
export default defineNuxtConfig({
  css: ['~/assets/theme.css'],
});

// theme-layer/app/app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#00dc82',
    darkMode: false,
  },
});

// consuming-app/nuxt.config.ts
export default defineNuxtConfig({
  extends: ['theme-layer'],
});

// consuming-app/app/app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: '#ff0000', // Override
  },
});

5.1 KiB Raw Blame History