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
andapp.config
- Create a component library using
app/components/
directory - Create utility and composable library using
app/composables/
andapp/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: [
'../base', // Extend from a local layer
'@my-themes/awesome', // Extend from an installed npm package
'github:my-themes/awesome#v1', // Extend from a git repository
]
})
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 how they override each other:
- Layers in
extends
- earlier entries have higher priority (first overrides second) - Auto-scanned local layers from
~~/layers
directory in alphabetical order (Z overrides A) - Your project has the highest priority in the stack - it will always override other layers
export default defineNuxtConfig({
extends: [
'../base', // Highest priority (among extends)
'@my-themes/awesome', // Medium priority
'github:my-themes/awesome#v1', // Lower priority
]
// Your project has the highest priority
})
This means if multiple layers define the same component, configuration, or file, the one with higher priority will be used.
Examples
Server
Build full-stack applications with Nuxt's server framework. You can fetch data from your database or another server, create APIs, or even generate static server-side content like a sitemap or a RSS feed - all from a single codebase.
Prerendering
Nuxt allows pages to be statically rendered at build time to improve certain performance or SEO metrics