Building and shipping team layers: anatomy, extends, priority and merging, publishing, testing, pitfalls.
Pages
- Anatomy of a layerA layer is a Nuxt app directory that another app merges in. What goes where, how Nuxt resolves its srcDir, and how to see the resolved layer list.
- extends and layer sourcesThe three places a layer can come from, the giget syntax for git layers, private repositories, and the auto-registered layers/ directory.
- Priority and mergingWhich layer wins when two define the same file or option, how c12 and defu merge configs, and how to prove the order instead of memorising it.
- Paths and aliases inside a layerWhy ~ and @ break inside a layer, the import.meta.url pattern, the
- Config merging in practiceHow modules, runtimeConfig, app.config, route rules, Vite options and environment overrides behave when a layer and a project both declare them.
- Overriding what a layer shipsHow a project replaces, wraps, extends or removes components, pages, layouts, composables, plugins, middleware and server routes inherited from a layer.
- Modules in layersLayers as module presets, how Nuxt deduplicates modules across layers, how module options merge, and how module authors make their modules layer-aware.
- Server code and Nitro in layersWhat a layer can ship under server/ and shared/, how Nitro merges handlers and config across layers, and why every route you ship is a security decision for every app.
- Publishing and consuming a layerThe layer starter and its playground, npm packaging rules, workspace versus registry versus git tags, the dev experience of each, and what counts as a breaking change.
- Testing a layer and CIThe playground as a test bench, fixture apps that extend the layer, asserting that overrides win, type-checking, and a CI matrix that catches Nuxt version skew before consumers do.
- Layers vs modules, and layers as architectureThe decision rule, the cases where a team needs both, domain-driven design with one layer per domain, and the places where a layer is the wrong tool.
- Pitfalls catalogueEighteen ways layers go wrong in practice, each with the symptom you will see, the cause underneath and the fix, plus code for the six that cost the most time.
- Designing a team layerThe senior-craft page for layers - defining a small public surface, theming through app.config, override recipes, performance and security costs per app, governance, and rolling out breaking changes.
Notes for the whole section