Layers

One of the core features of Nuxt is the layers and extending support. You can extend a default Nuxt application to reuse components, utils, and configuration. The layers structure is almost identical to a standard Nuxt application which makes them easy to author and maintain.

Use Cases

• Share reusable configuration presets across projects using nuxt.config and app.config
• Create a component library using components/ directory
• Create utility and composable library using composables/ and utils/ directories
• Create Nuxt module presets
• Share standard setup across projects
• Create Nuxt themes
• Enhance code organization by implementing a modular architecture and support Domain-Driven Design (DDD) pattern in large scale projects.

Usage

By default, any layers within your project in the ~~/layers directory will be automatically registered as layers in your project.

In addition, named layer aliases to the srcDir of each of these layers will automatically be created. For example, you will be able to access the ~~/layers/test layer via #layers/test.

In addition, you can extend from a layer by adding the extends property to your nuxt.config file.

export default defineNuxtConfig({
  extends: [
    // Extend from a local layer
    '../base',
    // Extend from an installed npm package
    '@my-themes/awesome',
    // Extend from a git repository
    'github:my-themes/awesome#v1',
  ],
})

You can also pass an authentication token if you are extending from a private GitHub repository:

export default defineNuxtConfig({
  extends: [
    // per layer configuration
    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }],
  ],
})

export default defineNuxtConfig({
  extends: [
    [
      'github:my-themes/awesome',
      {
        meta: {
          name: 'my-awesome-theme',
        },
      },
    ],
  ],
})

Nuxt uses unjs/c12 and unjs/giget for extending remote layers. Check the documentation for more information and all available options.

Layer Priority

When using multiple layers, it's important to understand the override order. Layers with higher priority override layers with lower priority when they define the same files or components.

Priority Order

From highest to lowest priority:

1. Your project files - always have the highest priority
2. Auto-scanned layers from ~~/layers directory - sorted alphabetically (Z has higher priority than A)
3. Layers in extends config - first entry has higher priority than second

Practical Example

Consider multiple layers defining the same component:

layers/
  1.base/
    components/Button.vue    # Base button style
  2.theme/
    components/Button.vue    # Themed button (overrides base)
app/
  components/Button.vue          # Project button (overrides all layers)

In this case:

• If only layers exist, 2.theme/Button.vue is used (higher alphabetically)
• If components/Button.vue exists in your project, it overrides all layers

Controlling Priority

You can prefix layer directories with numbers to control the order:

layers/
  1.base/        # Lowest priority
  2.features/    # Medium priority
  3.admin/       # Highest priority (among layers)

When to Use Each

• ~~/layers directory - Use for local layers that are part of your project
• extends - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory

Full Example with extends

export default defineNuxtConfig({
  extends: [
    '../base', // Local layer outside project
    '@my-themes/awesome', // NPM package
    'github:my-themes/awesome#v1', // Remote repository
  ],
})

If you also have ~~/layers/custom, the priority order is:

• Your project files (highest)
• ~~/layers/custom
• ../base
• @my-themes/awesome
• github:my-themes/awesome#v1 (lowest)

Examples