1---
2name: nuxt-layers
3description: Extending Nuxt applications with layers for code sharing and reusability
4---
5 
6# Nuxt Layers
7 
8Layers allow sharing and reusing partial Nuxt applications across projects. They can include components, composables, pages, layouts, and configuration.
9 
10## Using Layers
11 
12### From npm Package
13 
14```ts
15// nuxt.config.ts
16export default defineNuxtConfig({
17  extends: [
18    '@my-org/base-layer',
19    '@nuxtjs/ui-layer',
20  ],
21})
22```
23 
24### From Git Repository
25 
26```ts
27// nuxt.config.ts
28export default defineNuxtConfig({
29  extends: [
30    'github:username/repo',
31    'github:username/repo/base', // Subdirectory
32    'github:username/repo#v1.0', // Specific tag
33    'github:username/repo#dev', // Branch
34    'gitlab:username/repo',
35    'bitbucket:username/repo',
36  ],
37})
38```
39 
40### From Local Directory
41 
42```ts
43// nuxt.config.ts
44export default defineNuxtConfig({
45  extends: [
46    '../base-layer',
47    './layers/shared',
48  ],
49})
50```
51 
52### Auto-scanned Layers
53 
54Place in `layers/` directory for automatic discovery:
55 
56```
57my-app/
58├── layers/
59│   ├── base/
60│   │   └── nuxt.config.ts
61│   └── ui/
62│       └── nuxt.config.ts
63└── nuxt.config.ts
64```
65 
66## Creating a Layer
67 
68Minimal layer structure:
69 
70```
71my-layer/
72├── nuxt.config.ts       # Required
73├── app/
74│   ├── components/      # Auto-merged
75│   ├── composables/     # Auto-merged
76│   ├── layouts/         # Auto-merged
77│   ├── middleware/      # Auto-merged
78│   ├── pages/           # Auto-merged
79│   ├── plugins/         # Auto-merged
80│   └── app.config.ts    # Merged
81├── server/              # Auto-merged
82└── package.json
83```
84 
85### Layer nuxt.config.ts
86 
87```ts
88// my-layer/nuxt.config.ts
89export default defineNuxtConfig({
90  // Layer configuration
91  app: {
92    head: {
93      title: 'My Layer App',
94    },
95  },
96  // Shared modules
97  modules: ['@nuxt/ui'],
98})
99```
100 
101### Layer Components
102 
103```vue
104<!-- my-layer/app/components/BaseButton.vue -->
105<template>
106  <button class="base-btn">
107    <slot />
108  </button>
109</template>
110```
111 
112Use in consuming project:
113 
114```vue
115<template>
116  <BaseButton>Click me</BaseButton>
117</template>
118```
119 
120### Layer Composables
121 
122```ts
123// my-layer/app/composables/useTheme.ts
124export function useTheme() {
125  const isDark = useState('theme-dark', () => false)
126  const toggle = () => isDark.value = !isDark.value
127  return { isDark, toggle }
128}
129```
130 
131## Layer Priority
132 
133Override order (highest to lowest):
1341. Your project files
1352. Auto-scanned layers (alphabetically, Z > A)
1363. `extends` array (first > last)
137 
138Control order with prefixes:
139 
140```
141layers/
142├── 1.base/      # Lower priority
143└── 2.theme/     # Higher priority
144```
145 
146## Layer Aliases
147 
148Access layer files:
149 
150```ts
151// Auto-scanned layers get aliases
152import Component from '#layers/base/components/Component.vue'
153```
154 
155Named aliases:
156 
157```ts
158// my-layer/nuxt.config.ts
159export default defineNuxtConfig({
160  $meta: {
161    name: 'my-layer',
162  },
163})
164```
165 
166```ts
167// In consuming project
168import { something } from '#layers/my-layer/utils'
169```
170 
171## Publishing Layers
172 
173### As npm Package
174 
175```json
176{
177  "name": "my-nuxt-layer",
178  "version": "1.0.0",
179  "type": "module",
180  "main": "./nuxt.config.ts",
181  "dependencies": {
182    "@nuxt/ui": "^2.0.0"
183  },
184  "devDependencies": {
185    "nuxt": "^3.0.0"
186  }
187}
188```
189 
190### Private Layers
191 
192For private git repos:
193 
194```bash
195export GIGET_AUTH=<github-token>
196```
197 
198## Layer Best Practices
199 
200### Use Resolved Paths
201 
202```ts
203// my-layer/nuxt.config.ts
204import { fileURLToPath } from 'node:url'
205import { dirname, join } from 'node:path'
206 
207const currentDir = dirname(fileURLToPath(import.meta.url))
208 
209export default defineNuxtConfig({
210  css: [
211    join(currentDir, './assets/main.css'),
212  ],
213})
214```
215 
216### Install Dependencies
217 
218```ts
219// nuxt.config.ts
220export default defineNuxtConfig({
221  extends: [
222    ['github:user/layer', { install: true }],
223  ],
224})
225```
226 
227### Disable Layer Modules
228 
229```ts
230// nuxt.config.ts
231export default defineNuxtConfig({
232  extends: ['./base-layer'],
233  // Disable modules from layer
234  image: false, // Disables @nuxt/image
235  pinia: false, // Disables @pinia/nuxt
236})
237```
238 
239## Starter Template
240 
241Create a new layer:
242 
243```bash
244npx nuxi init --template layer my-layer
245```
246 
247## Example: Theme Layer
248 
249```
250theme-layer/
251├── nuxt.config.ts
252├── app/
253│   ├── app.config.ts
254│   ├── components/
255│   │   ├── ThemeButton.vue
256│   │   └── ThemeCard.vue
257│   ├── composables/
258│   │   └── useTheme.ts
259│   └── assets/
260│       └── theme.css
261└── package.json
262```
263 
264```ts
265// theme-layer/nuxt.config.ts
266export default defineNuxtConfig({
267  css: ['~/assets/theme.css'],
268})
269```
270 
271```ts
272// theme-layer/app/app.config.ts
273export default defineAppConfig({
274  theme: {
275    primaryColor: '#00dc82',
276    darkMode: false,
277  },
278})
279```
280 
281```ts
282// consuming-app/nuxt.config.ts
283export default defineNuxtConfig({
284  extends: ['theme-layer'],
285})
286 
287// consuming-app/app/app.config.ts
288export default defineAppConfig({
289  theme: {
290    primaryColor: '#ff0000', // Override
291  },
292})
293```
294 
295<!-- 
296Source references:
297- https://nuxt.com/docs/getting-started/layers
298- https://nuxt.com/docs/guide/going-further/layers
299-->
300