1# Nuxt Configuration
2 
3## When to Use
4 
5Configuring `nuxt.config.ts`, modules, auto-imports, runtime config, layers.
6 
7## Basic Structure
8 
9```ts
10// nuxt.config.ts
11export default defineNuxtConfig({
12  devtools: { enabled: true },
13 
14  modules: [
15    '@nuxtjs/tailwindcss',
16    '@pinia/nuxt'
17  ],
18 
19  runtimeConfig: {
20    // Private (server-only)
21    apiSecret: process.env.API_SECRET,
22 
23    public: {
24      // Public (client + server)
25      apiBase: process.env.API_BASE || 'http://localhost:3000'
26    }
27  },
28 
29  app: {
30    head: {
31      title: 'My App',
32      meta: [
33        { charset: 'utf-8' },
34        { name: 'viewport', content: 'width=device-width, initial-scale=1' }
35      ]
36    }
37  }
38})
39```
40 
41## Runtime Config
42 
43Access runtime config in app:
44 
45```ts
46// Server-side
47const config = useRuntimeConfig()
48console.log(config.apiSecret) // Available
49 
50// Client-side
51const config = useRuntimeConfig()
52console.log(config.public.apiBase) // Available
53console.log(config.apiSecret) // undefined (private)
54```
55 
56### Runtime Config Validation (Recommended)
57 
58Use `nuxt-safe-runtime-config` for type-safe runtime config with build-time validation:
59 
60```bash
61npx nuxi module add nuxt-safe-runtime-config
62```
63 
64**Benefits:**
65 
66- Build-time validation (catches missing env vars early)
67- Optional runtime validation (validates when server starts)
68- Auto-generated types (no manual type definitions needed)
69- No manual env var checks required (schema handles validation)
70 
71**Example with Valibot:**
72 
73```ts
74import { number, object, optional, string } from 'valibot'
75 
76export default defineNuxtConfig({
77  modules: ['nuxt-safe-runtime-config'],
78 
79  runtimeConfig: {
80    databaseUrl: process.env.DATABASE_URL,
81    secretKey: process.env.SECRET_KEY,
82    port: Number.parseInt(process.env.PORT || '3000'),
83    public: {
84      apiBase: process.env.PUBLIC_API_BASE,
85      appName: 'My App',
86    },
87  },
88 
89  safeRuntimeConfig: {
90    $schema: object({
91      public: object({
92        apiBase: string(),
93        appName: optional(string()),
94      }),
95      databaseUrl: string(),
96      secretKey: string(),
97      port: optional(number()),
98    }),
99    validateAtRuntime: true, // Optional: validate when server starts
100  },
101})
102```
103 
104**Usage:**
105 
106```ts
107// Auto-typed from schema - no generics needed
108const config = useSafeRuntimeConfig()
109// config.public.apiBase is string
110// config.databaseUrl is string
111```
112 
113**No manual env checks needed:**
114 
115```ts
116// ❌ Don't do this with nuxt-safe-runtime-config
117if (!config.databaseUrl) throw new Error('Missing DATABASE_URL')
118 
119// ✅ Schema validation handles it automatically
120// If env var is missing, build fails with detailed error
121```
122 
123Works with Zod, ArkType, or any Standard Schema library. See: https://github.com/onmax/nuxt-safe-runtime-config
124 
125## Auto-Imports
126 
127Nuxt auto-imports from these directories:
128 
129- `components/` - Vue components
130- `composables/` - Composition functions
131- `utils/` - Utility functions
132- `server/utils/` - Server utilities (server-only)
133 
134### Custom Auto-Imports
135 
136```ts
137export default defineNuxtConfig({
138  imports: {
139    dirs: [
140      'stores',
141      'types'
142    ]
143  }
144})
145```
146 
147### Disable Auto-Import
148 
149```ts
150export default defineNuxtConfig({
151  imports: {
152    autoImport: false
153  }
154})
155```
156 
157## Modules
158 
159```ts
160export default defineNuxtConfig({
161  modules: [
162    '@nuxtjs/tailwindcss',
163    '@pinia/nuxt',
164    '@vueuse/nuxt',
165    ['@nuxtjs/google-fonts', {
166      families: {
167        Inter: [400, 700]
168      }
169    }]
170  ]
171})
172```
173 
174## App Config
175 
176For non-sensitive config exposed to client:
177 
178```ts
179// app.config.ts
180export default defineAppConfig({
181  theme: {
182    primaryColor: '#3b82f6',
183    borderRadius: '0.5rem'
184  }
185})
186```
187 
188Access in app:
189 
190```ts
191const appConfig = useAppConfig()
192console.log(appConfig.theme.primaryColor)
193```
194 
195## TypeScript
196 
197```ts
198export default defineNuxtConfig({
199  typescript: {
200    strict: true,
201    typeCheck: true,
202    shim: false
203  }
204})
205```
206 
207## Build Configuration
208 
209```ts
210export default defineNuxtConfig({
211  build: {
212    transpile: ['some-package']
213  },
214 
215  vite: {
216    css: {
217      preprocessorOptions: {
218        scss: {
219          additionalData: '@use "@/assets/styles/variables" as *;'
220        }
221      }
222    }
223  }
224})
225```
226 
227## Route Rules
228 
229Pre-render, cache, or customize routes:
230 
231```ts
232export default defineNuxtConfig({
233  routeRules: {
234    '/': { prerender: true },
235    '/api/**': { cors: true },
236    '/admin/**': { ssr: false },
237    '/blog/**': { swr: 3600 } // Cache for 1 hour
238  }
239})
240```
241 
242### ISR Route Rules
243 
244Use `isr` for incremental static regeneration:
245 
246```ts
247export default defineNuxtConfig({
248  routeRules: {
249    '/': { prerender: true },        // Static at build time
250    '/**': { isr: 60 },              // Regenerate every 60s
251    '/package/**': { isr: 60 },      // ISR for dynamic routes
252    '/search': { isr: false, cache: false },  // No cache
253  }
254})
255```
256 
257### Route Rule Layouts (Nuxt 4.3+)
258 
259Apply layouts via route rules for centralized layout management:
260 
261```ts
262export default defineNuxtConfig({
263  routeRules: {
264    '/admin/**': { appLayout: 'admin' },
265    '/docs/**': { appLayout: 'docs' },
266    '/': { appLayout: 'default' }
267  }
268})
269```
270 
271**Benefits:** Centralized layout control, no need for `setPageLayout()` in every page.
272 
273## Inline Modules
274 
275Add conditional logic during nuxt prepare:
276 
277```ts
278export default defineNuxtConfig({
279  modules: [
280    // Inline function module
281    function (_, nuxt) {
282      if (nuxt.options._prepare) {
283        // Disable expensive operations during prepare
284        nuxt.options.pwa ||= {}
285        nuxt.options.pwa.pwaAssets ||= { disabled: true }
286      }
287    },
288    '@nuxtjs/tailwindcss',
289  ]
290})
291```
292 
293## Provider-Specific Modules
294 
295Use `std-env` to detect platform and configure accordingly:
296 
297```ts
298// modules/vercel-cache.ts
299import { defineNuxtModule } from 'nuxt/kit'
300import { provider } from 'std-env'
301 
302export default defineNuxtModule({
303  meta: { name: 'vercel-cache' },
304  setup(_, nuxt) {
305    if (provider !== 'vercel') return
306 
307    nuxt.hook('nitro:config', (nitroConfig) => {
308      nitroConfig.storage ||= {}
309      nitroConfig.storage.cache = {
310        driver: 'vercel-runtime-cache',
311        ...nitroConfig.storage.cache,
312      }
313    })
314  }
315})
316```
317 
318Then register in nuxt.config.ts:
319 
320```ts
321export default defineNuxtConfig({
322  modules: ['~/modules/vercel-cache']
323})
324```
325 
326## Experimental Features
327 
328```ts
329export default defineNuxtConfig({
330  future: {
331    compatibilityVersion: 4
332  },
333 
334  experimental: {
335    typedPages: true,
336    viewTransition: true,
337    payloadExtraction: true // Enable ISR/SWR payload extraction (Nuxt 4.3+)
338  }
339})
340```
341 
342**Payload extraction** (Nuxt 4.3+): Enables cached payloads during client navigation for ISR/SWR routes, improving performance.
343 
344## Nitro Config
345 
346Server engine configuration:
347 
348```ts
349export default defineNuxtConfig({
350  nitro: {
351    preset: 'vercel',
352    compressPublicAssets: true,
353    routeRules: {
354      '/api/**': { cors: true }
355    }
356  }
357})
358```
359 
360## Layers
361 
362Extend or share configuration:
363 
364```ts
365export default defineNuxtConfig({
366  extends: [
367    './base-layer'
368  ]
369})
370```
371 
372## Environment Variables
373 
374Use `.env` file:
375 
376```env
377API_SECRET=secret123
378API_BASE=https://api.example.com
379```
380 
381Access via runtimeConfig:
382 
383```ts
384export default defineNuxtConfig({
385  runtimeConfig: {
386    apiSecret: process.env.API_SECRET,
387    public: {
388      apiBase: process.env.API_BASE
389    }
390  }
391})
392```
393 
394## Best Practices
395 
396- **Use nuxt-safe-runtime-config** for runtime config with validation
397- **Public vs private** - keep secrets in private runtimeConfig
398- **App config** for non-sensitive client config
399- **Route rules** for performance (prerender, cache, SWR)
400- **Auto-imports** for cleaner code
401- **TypeScript strict mode** for better DX
402 
403## Common Mistakes
404 
405| ❌ Wrong                   | ✅ Right                     |
406| -------------------------- | ---------------------------- |
407| Hardcoded API URLs         | Use runtimeConfig.public     |
408| Secrets in app.config      | Use runtimeConfig (private)  |
409| Import everything manually | Let Nuxt auto-import         |
410| process.env in client code | Use useRuntimeConfig()       |
411| Manual env var validation  | Use nuxt-safe-runtime-config |
412| if (!config.x) throw error | Schema validation handles it |
413 
414## Resources
415 
416- Nuxt config: https://nuxt.com/docs/api/nuxt-config
417- Runtime config: https://nuxt.com/docs/guide/going-further/runtime-config
418- App config: https://nuxt.com/docs/guide/directory-structure/app-config
419- Modules: https://nuxt.com/modules
420