1---
2name: configuration
3description: Nuxt configuration files including nuxt.config.ts, app.config.ts, and runtime configuration
4---
5 
6# Nuxt Configuration
7 
8Nuxt uses configuration files to customize application behavior. The main configuration options are `nuxt.config.ts` for build-time settings and `app.config.ts` for runtime settings.
9 
10## nuxt.config.ts
11 
12The main configuration file at the root of your project:
13 
14```ts
15// nuxt.config.ts
16export default defineNuxtConfig({
17  // Configuration options
18  devtools: { enabled: true },
19  modules: ['@nuxt/ui'],
20})
21```
22 
23### Nuxt 4 Path Aliases
24 
25In Nuxt 4 the default `srcDir` is `app/`, so the path aliases changed:
26 
27| Alias | Resolves to |
28|-------|-------------|
29| `~` / `@` | `<rootDir>/app` |
30| `~~` / `@@` | `<rootDir>` (project root) |
31| `#shared` | `<rootDir>/shared` |
32| `#server` | `<rootDir>/server` |
33 
34Reference root-level paths (modules, server handlers) with `~~` or `#server`:
35 
36```ts
37export default defineNuxtConfig({
38  modules: ['~~/custom-modules/awesome.js'], // relative to rootDir
39  serverHandlers: [
40    { route: '/foo/**', handler: '#server/foohandler.ts' },
41  ],
42})
43```
44 
45### Compatibility Version
46 
47Nuxt 4 is the default behavior. To preview upcoming Nuxt 5 defaults (Vite Environment API, normalized page names, etc.):
48 
49```ts
50export default defineNuxtConfig({
51  future: {
52    compatibilityVersion: 5,
53  },
54})
55```
56 
57### Environment Overrides
58 
59Configure environment-specific settings:
60 
61```ts
62export default defineNuxtConfig({
63  $production: {
64    routeRules: {
65      '/**': { isr: true },
66    },
67  },
68  $development: {
69    // Development-specific config
70  },
71  $env: {
72    staging: {
73      // Staging environment config
74    },
75  },
76})
77```
78 
79Use `--envName` flag to select environment: `nuxt build --envName staging`
80 
81## Runtime Config
82 
83For values that need to be overridden via environment variables:
84 
85```ts
86// nuxt.config.ts
87export default defineNuxtConfig({
88  runtimeConfig: {
89    // Server-only keys
90    apiSecret: '123',
91    // Keys within public are exposed to client
92    public: {
93      apiBase: '/api',
94    },
95  },
96})
97```
98 
99Override with environment variables:
100 
101```ini
102# .env
103NUXT_API_SECRET=api_secret_token
104NUXT_PUBLIC_API_BASE=https://api.example.com
105```
106 
107Access in components/composables:
108 
109```vue
110<script setup lang="ts">
111const config = useRuntimeConfig()
112// Server: config.apiSecret, config.public.apiBase
113// Client: config.public.apiBase only
114</script>
115```
116 
117## App Config
118 
119For public tokens determined at build time (not overridable via env vars):
120 
121```ts
122// app/app.config.ts
123export default defineAppConfig({
124  title: 'Hello Nuxt',
125  theme: {
126    dark: true,
127    colors: {
128      primary: '#ff0000',
129    },
130  },
131})
132```
133 
134Access in components:
135 
136```vue
137<script setup lang="ts">
138const appConfig = useAppConfig()
139</script>
140```
141 
142## runtimeConfig vs app.config
143 
144| Feature | runtimeConfig | app.config |
145|---------|--------------|------------|
146| Client-side | Hydrated | Bundled |
147| Environment variables | Yes | No |
148| Reactive | Yes | Yes |
149| Hot module replacement | No | Yes |
150| Non-primitive JS types | No | Yes |
151 
152**Use runtimeConfig** for secrets and values that change per environment.
153**Use app.config** for public tokens, theme settings, and non-sensitive config.
154 
155## External Tool Configuration
156 
157Nuxt uses `nuxt.config.ts` as single source of truth. Configure external tools within it:
158 
159```ts
160export default defineNuxtConfig({
161  // Nitro configuration
162  nitro: {
163    // nitro options
164  },
165  // Vite configuration
166  vite: {
167    // vite options
168    vue: {
169      // @vitejs/plugin-vue options
170    },
171  },
172  // PostCSS configuration
173  postcss: {
174    // postcss options
175  },
176})
177```
178 
179### Environment-specific Vite Config
180 
181Top-level `vite` options are shared. Use `$client` and `$server` to target a single Vite build:
182 
183```ts
184export default defineNuxtConfig({
185  vite: {
186    $client: {
187      build: { rollupOptions: { output: { manualChunks: { analytics: ['analytics-package'] } } } },
188    },
189    $server: {
190      build: { sourcemap: 'inline' },
191    },
192  },
193})
194```
195 
196## Vue Configuration
197 
198Enable Vue experimental features:
199 
200```ts
201export default defineNuxtConfig({
202  vue: {
203    propsDestructure: true,
204  },
205})
206```
207 
208## Experimental Features & Defaults
209 
210Notable Nuxt 4 flags under `experimental` (see source for the full list):
211 
212```ts
213export default defineNuxtConfig({
214  experimental: {
215    // Stream the HTML shell first, then render body progressively (better TTFB)
216    ssrStreaming: true,
217    // Run useFetch when its key changes even if immediate:false and not yet triggered
218    alwaysRunFetchOnKeyChange: true,
219    // Split useAsyncData handlers into separate chunks (static builds)
220    extractAsyncDataHandlers: true,
221    // pending is true before fetching starts
222    pendingWhenIdle: true,
223    // Default options for core composables/components
224    defaults: {
225      nuxtLink: { prefetch: true, prefetchOn: { visibility: true } },
226      useAsyncData: { deep: true },
227      useState: { resetOnClear: true },
228    },
229  },
230})
231```
232 
233<!-- 
234Source references:
235- https://nuxt.com/docs/4.x/getting-started/configuration
236- https://nuxt.com/docs/4.x/guide/going-further/runtime-config
237- https://nuxt.com/docs/4.x/api/nuxt-config
238- https://nuxt.com/docs/4.x/guide/going-further/experimental-features
239-->
240