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### Environment Overrides
24 
25Configure environment-specific settings:
26 
27```ts
28export default defineNuxtConfig({
29  $production: {
30    routeRules: {
31      '/**': { isr: true },
32    },
33  },
34  $development: {
35    // Development-specific config
36  },
37  $env: {
38    staging: {
39      // Staging environment config
40    },
41  },
42})
43```
44 
45Use `--envName` flag to select environment: `nuxt build --envName staging`
46 
47## Runtime Config
48 
49For values that need to be overridden via environment variables:
50 
51```ts
52// nuxt.config.ts
53export default defineNuxtConfig({
54  runtimeConfig: {
55    // Server-only keys
56    apiSecret: '123',
57    // Keys within public are exposed to client
58    public: {
59      apiBase: '/api',
60    },
61  },
62})
63```
64 
65Override with environment variables:
66 
67```ini
68# .env
69NUXT_API_SECRET=api_secret_token
70NUXT_PUBLIC_API_BASE=https://api.example.com
71```
72 
73Access in components/composables:
74 
75```vue
76<script setup lang="ts">
77const config = useRuntimeConfig()
78// Server: config.apiSecret, config.public.apiBase
79// Client: config.public.apiBase only
80</script>
81```
82 
83## App Config
84 
85For public tokens determined at build time (not overridable via env vars):
86 
87```ts
88// app/app.config.ts
89export default defineAppConfig({
90  title: 'Hello Nuxt',
91  theme: {
92    dark: true,
93    colors: {
94      primary: '#ff0000',
95    },
96  },
97})
98```
99 
100Access in components:
101 
102```vue
103<script setup lang="ts">
104const appConfig = useAppConfig()
105</script>
106```
107 
108## runtimeConfig vs app.config
109 
110| Feature | runtimeConfig | app.config |
111|---------|--------------|------------|
112| Client-side | Hydrated | Bundled |
113| Environment variables | Yes | No |
114| Reactive | Yes | Yes |
115| Hot module replacement | No | Yes |
116| Non-primitive JS types | No | Yes |
117 
118**Use runtimeConfig** for secrets and values that change per environment.
119**Use app.config** for public tokens, theme settings, and non-sensitive config.
120 
121## External Tool Configuration
122 
123Nuxt uses `nuxt.config.ts` as single source of truth. Configure external tools within it:
124 
125```ts
126export default defineNuxtConfig({
127  // Nitro configuration
128  nitro: {
129    // nitro options
130  },
131  // Vite configuration
132  vite: {
133    // vite options
134    vue: {
135      // @vitejs/plugin-vue options
136    },
137  },
138  // PostCSS configuration
139  postcss: {
140    // postcss options
141  },
142})
143```
144 
145## Vue Configuration
146 
147Enable Vue experimental features:
148 
149```ts
150export default defineNuxtConfig({
151  vue: {
152    propsDestructure: true,
153  },
154})
155```
156 
157<!-- 
158Source references:
159- https://nuxt.com/docs/getting-started/configuration
160- https://nuxt.com/docs/guide/going-further/runtime-config
161- https://nuxt.com/docs/api/nuxt-config
162-->
163