@nuxt/docs 3.19.2 → 3.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. package/1.getting-started/01.introduction.md +2 -2
  2. package/1.getting-started/02.installation.md +2 -1
  3. package/1.getting-started/03.configuration.md +29 -29
  4. package/1.getting-started/04.views.md +7 -7
  5. package/1.getting-started/05.assets.md +15 -9
  6. package/1.getting-started/06.styling.md +55 -45
  7. package/1.getting-started/07.routing.md +12 -12
  8. package/1.getting-started/08.seo-meta.md +55 -42
  9. package/1.getting-started/09.transitions.md +47 -42
  10. package/1.getting-started/10.data-fetching.md +90 -67
  11. package/1.getting-started/11.state-management.md +22 -15
  12. package/1.getting-started/12.error-handling.md +11 -9
  13. package/1.getting-started/13.server.md +3 -3
  14. package/1.getting-started/14.layers.md +21 -15
  15. package/1.getting-started/15.prerendering.md +28 -28
  16. package/1.getting-started/16.deployment.md +9 -9
  17. package/1.getting-started/17.testing.md +43 -43
  18. package/1.getting-started/18.upgrade.md +66 -61
  19. package/2.guide/0.index.md +3 -3
  20. package/2.guide/{2.directory-structure → 1.directory-structure}/.navigation.yml +1 -1
  21. package/2.guide/{2.directory-structure → 1.directory-structure}/0.nuxt.md +3 -3
  22. package/2.guide/{2.directory-structure → 1.directory-structure}/0.output.md +3 -3
  23. package/2.guide/{2.directory-structure → 1.directory-structure}/1.assets.md +3 -3
  24. package/2.guide/{2.directory-structure → 1.directory-structure}/1.components.md +41 -24
  25. package/2.guide/{2.directory-structure → 1.directory-structure}/1.composables.md +11 -11
  26. package/2.guide/{2.directory-structure → 1.directory-structure}/1.content.md +7 -4
  27. package/2.guide/{2.directory-structure → 1.directory-structure}/1.layouts.md +16 -12
  28. package/2.guide/{2.directory-structure → 1.directory-structure}/1.middleware.md +28 -22
  29. package/2.guide/{2.directory-structure → 1.directory-structure}/1.modules.md +6 -6
  30. package/2.guide/{2.directory-structure → 1.directory-structure}/1.node_modules.md +2 -2
  31. package/2.guide/{2.directory-structure → 1.directory-structure}/1.pages.md +33 -31
  32. package/2.guide/{2.directory-structure → 1.directory-structure}/1.plugins.md +25 -25
  33. package/2.guide/{2.directory-structure → 1.directory-structure}/1.public.md +2 -2
  34. package/2.guide/{2.directory-structure → 1.directory-structure}/1.server.md +34 -34
  35. package/2.guide/{2.directory-structure → 1.directory-structure}/1.shared.md +6 -6
  36. package/2.guide/{2.directory-structure → 1.directory-structure}/1.utils.md +5 -5
  37. package/2.guide/{2.directory-structure → 1.directory-structure}/2.env.md +5 -5
  38. package/2.guide/{2.directory-structure → 1.directory-structure}/2.gitignore.md +1 -1
  39. package/2.guide/{2.directory-structure → 1.directory-structure}/2.nuxtignore.md +4 -4
  40. package/2.guide/{2.directory-structure → 1.directory-structure}/2.nuxtrc.md +3 -3
  41. package/2.guide/{2.directory-structure → 1.directory-structure}/3.app-config.md +12 -12
  42. package/2.guide/{2.directory-structure → 1.directory-structure}/3.app.md +4 -4
  43. package/2.guide/{2.directory-structure → 1.directory-structure}/3.error.md +6 -6
  44. package/2.guide/{2.directory-structure → 1.directory-structure}/3.nuxt-config.md +2 -2
  45. package/2.guide/{2.directory-structure → 1.directory-structure}/3.package.md +1 -1
  46. package/2.guide/{2.directory-structure → 1.directory-structure}/3.tsconfig.md +3 -3
  47. package/2.guide/{1.concepts → 2.concepts}/1.auto-imports.md +18 -18
  48. package/2.guide/{1.concepts → 2.concepts}/10.nuxt-lifecycle.md +10 -10
  49. package/2.guide/{1.concepts → 2.concepts}/2.vuejs-development.md +9 -9
  50. package/2.guide/{1.concepts → 2.concepts}/3.rendering.md +21 -19
  51. package/2.guide/{1.concepts → 2.concepts}/4.server-engine.md +5 -5
  52. package/2.guide/{1.concepts → 2.concepts}/5.modules.md +4 -4
  53. package/2.guide/{1.concepts → 2.concepts}/7.esm.md +20 -14
  54. package/2.guide/{1.concepts → 2.concepts}/8.typescript.md +11 -11
  55. package/2.guide/3.going-further/1.events.md +2 -2
  56. package/2.guide/3.going-further/1.experimental-features.md +168 -80
  57. package/2.guide/3.going-further/1.features.md +15 -15
  58. package/2.guide/3.going-further/1.internals.md +25 -25
  59. package/2.guide/3.going-further/10.runtime-config.md +11 -11
  60. package/2.guide/3.going-further/2.hooks.md +11 -11
  61. package/2.guide/3.going-further/3.modules.md +119 -101
  62. package/2.guide/3.going-further/4.kit.md +5 -5
  63. package/2.guide/3.going-further/6.nuxt-app.md +5 -5
  64. package/2.guide/3.going-further/7.layers.md +75 -58
  65. package/2.guide/3.going-further/9.debugging.md +2 -2
  66. package/2.guide/4.recipes/1.custom-routing.md +31 -31
  67. package/2.guide/4.recipes/2.vite-plugin.md +45 -4
  68. package/2.guide/4.recipes/3.custom-usefetch.md +12 -12
  69. package/2.guide/4.recipes/4.sessions-and-authentication.md +34 -20
  70. package/2.guide/5.best-practices/hydration.md +4 -4
  71. package/2.guide/5.best-practices/performance.md +12 -12
  72. package/3.api/1.components/1.client-only.md +6 -3
  73. package/3.api/1.components/1.nuxt-client-fallback.md +9 -6
  74. package/3.api/1.components/10.nuxt-picture.md +1 -1
  75. package/3.api/1.components/11.teleports.md +4 -1
  76. package/3.api/1.components/12.nuxt-route-announcer.md +9 -9
  77. package/3.api/1.components/13.nuxt-time.md +49 -18
  78. package/3.api/1.components/2.nuxt-page.md +4 -4
  79. package/3.api/1.components/3.nuxt-layout.md +11 -6
  80. package/3.api/1.components/4.nuxt-link.md +40 -20
  81. package/3.api/1.components/5.nuxt-loading-indicator.md +2 -2
  82. package/3.api/1.components/6.nuxt-error-boundary.md +11 -9
  83. package/3.api/2.composables/on-prehydrate.md +2 -2
  84. package/3.api/2.composables/use-async-data.md +23 -19
  85. package/3.api/2.composables/use-cookie.md +28 -20
  86. package/3.api/2.composables/use-error.md +1 -1
  87. package/3.api/2.composables/use-fetch.md +59 -29
  88. package/3.api/2.composables/use-head-safe.md +7 -7
  89. package/3.api/2.composables/use-head.md +4 -4
  90. package/3.api/2.composables/use-hydration.md +6 -6
  91. package/3.api/2.composables/use-lazy-async-data.md +2 -2
  92. package/3.api/2.composables/use-lazy-fetch.md +2 -2
  93. package/3.api/2.composables/use-loading-indicator.md +12 -12
  94. package/3.api/2.composables/use-nuxt-app.md +19 -19
  95. package/3.api/2.composables/use-nuxt-data.md +8 -8
  96. package/3.api/2.composables/use-preview-mode.md +15 -18
  97. package/3.api/2.composables/use-request-event.md +1 -1
  98. package/3.api/2.composables/use-request-fetch.md +3 -3
  99. package/3.api/2.composables/use-request-header.md +1 -1
  100. package/3.api/2.composables/use-request-headers.md +4 -4
  101. package/3.api/2.composables/use-request-url.md +1 -1
  102. package/3.api/2.composables/use-response-header.md +9 -10
  103. package/3.api/2.composables/use-route-announcer.md +4 -4
  104. package/3.api/2.composables/use-route.md +1 -1
  105. package/3.api/2.composables/use-router.md +9 -7
  106. package/3.api/2.composables/use-runtime-config.md +6 -6
  107. package/3.api/2.composables/use-runtime-hook.md +2 -2
  108. package/3.api/2.composables/use-seo-meta.md +2 -2
  109. package/3.api/2.composables/use-server-seo-meta.md +4 -4
  110. package/3.api/2.composables/use-state.md +4 -4
  111. package/3.api/3.utils/$fetch.md +9 -7
  112. package/3.api/3.utils/abort-navigation.md +3 -3
  113. package/3.api/3.utils/add-route-middleware.md +5 -5
  114. package/3.api/3.utils/call-once.md +4 -4
  115. package/3.api/3.utils/clear-error.md +2 -2
  116. package/3.api/3.utils/clear-nuxt-data.md +3 -3
  117. package/3.api/3.utils/clear-nuxt-state.md +3 -3
  118. package/3.api/3.utils/create-error.md +1 -1
  119. package/3.api/3.utils/define-lazy-hydration-component.md +13 -13
  120. package/3.api/3.utils/define-nuxt-component.md +5 -5
  121. package/3.api/3.utils/define-nuxt-plugin.md +12 -12
  122. package/3.api/3.utils/define-nuxt-route-middleware.md +5 -5
  123. package/3.api/3.utils/define-page-meta.md +21 -21
  124. package/3.api/3.utils/define-route-rules.md +5 -5
  125. package/3.api/3.utils/navigate-to.md +10 -10
  126. package/3.api/3.utils/prefetch-components.md +1 -1
  127. package/3.api/3.utils/preload-components.md +1 -1
  128. package/3.api/3.utils/prerender-routes.md +3 -3
  129. package/3.api/3.utils/refresh-cookie.md +3 -3
  130. package/3.api/3.utils/refresh-nuxt-data.md +11 -6
  131. package/3.api/3.utils/reload-nuxt-app.md +2 -2
  132. package/3.api/3.utils/set-page-layout.md +1 -1
  133. package/3.api/3.utils/set-response-status.md +2 -2
  134. package/3.api/3.utils/show-error.md +4 -4
  135. package/3.api/3.utils/update-app-config.md +3 -2
  136. package/3.api/4.commands/add.md +1 -1
  137. package/3.api/4.commands/analyze.md +2 -1
  138. package/3.api/4.commands/build.md +2 -1
  139. package/3.api/4.commands/dev.md +5 -4
  140. package/3.api/4.commands/generate.md +2 -1
  141. package/3.api/4.commands/init.md +3 -2
  142. package/3.api/4.commands/module.md +4 -4
  143. package/3.api/4.commands/prepare.md +7 -2
  144. package/3.api/4.commands/preview.md +5 -4
  145. package/3.api/4.commands/test.md +40 -0
  146. package/3.api/4.commands/typecheck.md +4 -2
  147. package/3.api/4.commands/upgrade.md +3 -3
  148. package/3.api/5.kit/1.modules.md +123 -37
  149. package/3.api/5.kit/10.runtime-config.md +1 -1
  150. package/3.api/5.kit/10.templates.md +8 -6
  151. package/3.api/5.kit/11.nitro.md +66 -62
  152. package/3.api/5.kit/12.resolving.md +2 -2
  153. package/3.api/5.kit/14.builder.md +61 -4
  154. package/3.api/5.kit/15.examples.md +5 -7
  155. package/3.api/5.kit/16.layers.md +26 -26
  156. package/3.api/5.kit/3.compatibility.md +12 -12
  157. package/3.api/5.kit/4.autoimports.md +13 -13
  158. package/3.api/5.kit/5.components.md +8 -7
  159. package/3.api/5.kit/6.context.md +3 -3
  160. package/3.api/5.kit/7.pages.md +7 -7
  161. package/3.api/5.kit/8.layout.md +2 -2
  162. package/3.api/5.kit/9.head.md +132 -0
  163. package/3.api/5.kit/9.plugins.md +6 -5
  164. package/3.api/6.advanced/1.hooks.md +4 -4
  165. package/3.api/6.advanced/2.import-meta.md +3 -3
  166. package/5.community/2.getting-help.md +1 -1
  167. package/5.community/3.reporting-bugs.md +1 -1
  168. package/5.community/4.contribution.md +6 -6
  169. package/5.community/5.framework-contribution.md +3 -3
  170. package/5.community/6.roadmap.md +1 -1
  171. package/6.bridge/1.overview.md +13 -13
  172. package/6.bridge/10.configuration.md +2 -1
  173. package/6.bridge/2.typescript.md +2 -2
  174. package/6.bridge/3.bridge-composition-api.md +6 -6
  175. package/6.bridge/4.plugins-and-middleware.md +9 -9
  176. package/6.bridge/5.nuxt3-compatible-api.md +19 -16
  177. package/6.bridge/6.meta.md +20 -19
  178. package/6.bridge/7.runtime-config.md +1 -1
  179. package/6.bridge/8.nitro.md +3 -3
  180. package/6.bridge/9.vite.md +4 -4
  181. package/7.migration/1.overview.md +2 -2
  182. package/7.migration/2.configuration.md +22 -20
  183. package/7.migration/20.module-authors.md +6 -6
  184. package/7.migration/3.auto-imports.md +3 -3
  185. package/7.migration/4.meta.md +20 -17
  186. package/7.migration/5.plugins-and-middleware.md +5 -5
  187. package/7.migration/6.pages-and-layouts.md +23 -19
  188. package/7.migration/7.component-options.md +14 -14
  189. package/7.migration/8.runtime-config.md +6 -6
  190. package/package.json +1 -1
  191. /package/2.guide/{1.concepts → 2.concepts}/.navigation.yml +0 -0
  192. /package/2.guide/{1.concepts → 2.concepts}/9.code-style.md +0 -0
@@ -5,7 +5,7 @@ description: "Enable Nuxt experimental features to unlock new possibilities."
5
5
 
6
6
  The Nuxt experimental features can be enabled in the Nuxt configuration file.
7
7
 
8
- Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
8
+ Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/3.x/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
9
9
 
10
10
  ::note
11
11
  Note that these features are experimental and could be removed or modified in the future.
@@ -18,8 +18,8 @@ Enable native async context to be accessible for nested composables in Nuxt and
18
18
  ```ts twoslash [nuxt.config.ts]
19
19
  export default defineNuxtConfig({
20
20
  experimental: {
21
- asyncContext: true
22
- }
21
+ asyncContext: true,
22
+ },
23
23
  })
24
24
  ```
25
25
 
@@ -34,8 +34,8 @@ Enables generation of an async entry point for the Vue bundle, aiding module fed
34
34
  ```ts twoslash [nuxt.config.ts]
35
35
  export default defineNuxtConfig({
36
36
  experimental: {
37
- asyncEntry: true
38
- }
37
+ asyncEntry: true,
38
+ },
39
39
  })
40
40
  ```
41
41
 
@@ -48,8 +48,8 @@ Externalizes `vue`, `@vue/*` and `vue-router` when building.
48
48
  ```ts twoslash [nuxt.config.ts]
49
49
  export default defineNuxtConfig({
50
50
  experimental: {
51
- externalVue: true
52
- }
51
+ externalVue: true,
52
+ },
53
53
  })
54
54
  ```
55
55
 
@@ -66,55 +66,93 @@ Tree shakes contents of client-only components from server bundle.
66
66
  ```ts twoslash [nuxt.config.ts]
67
67
  export default defineNuxtConfig({
68
68
  experimental: {
69
- treeshakeClientOnly: true
70
- }
69
+ treeshakeClientOnly: true,
70
+ },
71
71
  })
72
72
  ```
73
73
 
74
+ ## extractAsyncDataHandlers
75
+
76
+ Extracts handler functions from `useAsyncData` and `useLazyAsyncData` calls into separate chunks for improved code splitting and caching efficiency.
77
+
78
+ ```ts twoslash [nuxt.config.ts]
79
+ export default defineNuxtConfig({
80
+ experimental: {
81
+ extractAsyncDataHandlers: true,
82
+ },
83
+ })
84
+ ```
85
+
86
+ This feature transforms inline handler functions into dynamically imported chunks:
87
+
88
+ ```vue
89
+ <!-- Before -->
90
+ <script setup>
91
+ const { data } = await useAsyncData('user', async () => {
92
+ return await $fetch('/api/user')
93
+ })
94
+ </script>
95
+ ```
96
+
97
+ ```vue
98
+ <!-- After transformation -->
99
+ <script setup>
100
+ const { data } = await useAsyncData('user', () =>
101
+ import('/generated-chunk.js').then(r => r.default()),
102
+ )
103
+ </script>
104
+ ```
105
+
106
+ The benefit of this transformation is that we can split out data fetching logic &mdash; while still allowing the code to be loaded if required.
107
+
108
+ ::important
109
+ This feature is only recommended for **static builds** with payload extraction, and where data does not need to be re-fetched at runtime.
110
+ ::
111
+
74
112
  ## emitRouteChunkError
75
113
 
76
114
  Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a reload of the new route on navigation to a new route when a chunk fails to load.
77
115
 
78
- If you set this to `'automatic-immediate'` Nuxt will reload the current route immediately, instead of waiting for a navigation. This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/guide/directory-structure/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
116
+ If you set this to `'automatic-immediate'` Nuxt will reload the current route immediately, instead of waiting for a navigation. This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/3.x/guide/directory-structure/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
79
117
 
80
118
  You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
81
119
 
82
120
  ```ts twoslash [nuxt.config.ts]
83
121
  export default defineNuxtConfig({
84
122
  experimental: {
85
- emitRouteChunkError: 'automatic' // or 'automatic-immediate', 'manual' or false
86
- }
123
+ emitRouteChunkError: 'automatic', // or 'automatic-immediate', 'manual' or false
124
+ },
87
125
  })
88
126
  ```
89
127
 
90
128
  ## restoreState
91
129
 
92
- Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/api/utils/reload-nuxt-app) call.
130
+ Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/3.x/api/utils/reload-nuxt-app) call.
93
131
 
94
132
  To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.
95
133
 
96
134
  ::important
97
135
  Consider carefully before enabling this as it can cause unexpected behavior,
98
- and consider providing explicit keys to [`useState`](/docs/api/composables/use-state) as auto-generated keys may not match across builds.
136
+ and consider providing explicit keys to [`useState`](/docs/3.x/api/composables/use-state) as auto-generated keys may not match across builds.
99
137
  ::
100
138
 
101
139
  ```ts twoslash [nuxt.config.ts]
102
140
  export default defineNuxtConfig({
103
141
  experimental: {
104
- restoreState: true
105
- }
142
+ restoreState: true,
143
+ },
106
144
  })
107
145
  ```
108
146
 
109
147
  ## inlineRouteRules
110
148
 
111
- Define route rules at the page level using [`defineRouteRules`](/docs/api/utils/define-route-rules).
149
+ Define route rules at the page level using [`defineRouteRules`](/docs/3.x/api/utils/define-route-rules).
112
150
 
113
151
  ```ts twoslash [nuxt.config.ts]
114
152
  export default defineNuxtConfig({
115
153
  experimental: {
116
- inlineRouteRules: true
117
- }
154
+ inlineRouteRules: true,
155
+ },
118
156
  })
119
157
  ```
120
158
 
@@ -135,8 +173,8 @@ Allows rendering of JSON payloads with support for revivifying complex types.
135
173
  ```ts twoslash [nuxt.config.ts]
136
174
  export default defineNuxtConfig({
137
175
  experimental: {
138
- renderJsonPayloads: true
139
- }
176
+ renderJsonPayloads: true,
177
+ },
140
178
  })
141
179
  ```
142
180
 
@@ -147,8 +185,8 @@ Disables Vue server renderer endpoint within Nitro.
147
185
  ```ts twoslash [nuxt.config.ts]
148
186
  export default defineNuxtConfig({
149
187
  experimental: {
150
- noVueServer: true
151
- }
188
+ noVueServer: true,
189
+ },
152
190
  })
153
191
  ```
154
192
 
@@ -159,20 +197,20 @@ Enables extraction of payloads of pages generated with `nuxt generate`.
159
197
  ```ts twoslash [nuxt.config.ts]
160
198
  export default defineNuxtConfig({
161
199
  experimental: {
162
- payloadExtraction: true
163
- }
200
+ payloadExtraction: true,
201
+ },
164
202
  })
165
203
  ```
166
204
 
167
205
  ## clientFallback
168
206
 
169
- Enables the experimental [`<NuxtClientFallback>`](/docs/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
207
+ Enables the experimental [`<NuxtClientFallback>`](/docs/3.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.
170
208
 
171
209
  ```ts twoslash [nuxt.config.ts]
172
210
  export default defineNuxtConfig({
173
211
  experimental: {
174
- clientFallback: true
175
- }
212
+ clientFallback: true,
213
+ },
176
214
  })
177
215
  ```
178
216
 
@@ -183,8 +221,8 @@ Enables cross-origin prefetch using the Speculation Rules API.
183
221
  ```ts twoslash [nuxt.config.ts]
184
222
  export default defineNuxtConfig({
185
223
  experimental: {
186
- crossOriginPrefetch: true
187
- }
224
+ crossOriginPrefetch: true,
225
+ },
188
226
  })
189
227
  ```
190
228
 
@@ -199,8 +237,8 @@ Enables View Transition API integration with client-side router.
199
237
  ```ts twoslash [nuxt.config.ts]
200
238
  export default defineNuxtConfig({
201
239
  experimental: {
202
- viewTransition: true
203
- }
240
+ viewTransition: true,
241
+ },
204
242
  })
205
243
  ```
206
244
 
@@ -217,20 +255,20 @@ Enables writing of early hints when using node server.
217
255
  ```ts twoslash [nuxt.config.ts]
218
256
  export default defineNuxtConfig({
219
257
  experimental: {
220
- writeEarlyHints: true
221
- }
258
+ writeEarlyHints: true,
259
+ },
222
260
  })
223
261
  ```
224
262
 
225
263
  ## componentIslands
226
264
 
227
- Enables experimental component islands support with [`<NuxtIsland>`](/docs/api/components/nuxt-island) and `.island.vue` files.
265
+ Enables experimental component islands support with [`<NuxtIsland>`](/docs/3.x/api/components/nuxt-island) and `.island.vue` files.
228
266
 
229
267
  ```ts twoslash [nuxt.config.ts]
230
268
  export default defineNuxtConfig({
231
269
  experimental: {
232
- componentIslands: true // false or 'local+remote'
233
- }
270
+ componentIslands: true, // false or 'local+remote'
271
+ },
234
272
  })
235
273
  ```
236
274
 
@@ -249,8 +287,8 @@ Enables config schema support.
249
287
  ```ts twoslash [nuxt.config.ts]
250
288
  export default defineNuxtConfig({
251
289
  experimental: {
252
- configSchema: true
253
- }
290
+ configSchema: true,
291
+ },
254
292
  })
255
293
  ```
256
294
 
@@ -261,8 +299,8 @@ Adds a compatibility layer for modules, plugins, or user code relying on the old
261
299
  ```ts twoslash [nuxt.config.ts]
262
300
  export default defineNuxtConfig({
263
301
  experimental: {
264
- polyfillVueUseHead: false
265
- }
302
+ polyfillVueUseHead: false,
303
+ },
266
304
  })
267
305
  ```
268
306
 
@@ -273,8 +311,8 @@ Allow disabling Nuxt SSR responses by setting the `x-nuxt-no-ssr` header.
273
311
  ```ts twoslash [nuxt.config.ts]
274
312
  export default defineNuxtConfig({
275
313
  experimental: {
276
- respectNoSSRHeader: false
277
- }
314
+ respectNoSSRHeader: false,
315
+ },
278
316
  })
279
317
  ```
280
318
 
@@ -287,8 +325,8 @@ Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to th
287
325
  ```ts twoslash [nuxt.config.ts]
288
326
  export default defineNuxtConfig({
289
327
  experimental: {
290
- localLayerAliases: true
291
- }
328
+ localLayerAliases: true,
329
+ },
292
330
  })
293
331
  ```
294
332
 
@@ -299,12 +337,12 @@ Enable the new experimental typed router using [`unplugin-vue-router`](https://g
299
337
  ```ts twoslash [nuxt.config.ts]
300
338
  export default defineNuxtConfig({
301
339
  experimental: {
302
- typedPages: true
303
- }
340
+ typedPages: true,
341
+ },
304
342
  })
305
343
  ```
306
344
 
307
- Out of the box, this will enable typed usage of [`navigateTo`](/docs/api/utils/navigate-to), [`<NuxtLink>`](/docs/api/components/nuxt-link), [`router.push()`](/docs/api/composables/use-router) and more.
345
+ Out of the box, this will enable typed usage of [`navigateTo`](/docs/3.x/api/utils/navigate-to), [`<NuxtLink>`](/docs/3.x/api/components/nuxt-link), [`router.push()`](/docs/3.x/api/composables/use-router) and more.
308
346
 
309
347
  You can even get typed params within a page by using `const route = useRoute('route-name')`.
310
348
 
@@ -329,8 +367,8 @@ You can also set this to `chokidar` to watch all files in your source directory.
329
367
  ```ts twoslash [nuxt.config.ts]
330
368
  export default defineNuxtConfig({
331
369
  experimental: {
332
- watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
333
- }
370
+ watcher: 'chokidar-granular', // 'chokidar' or 'parcel' are also options
371
+ },
334
372
  })
335
373
  ```
336
374
 
@@ -343,8 +381,8 @@ fetch the same data in different pages.
343
381
  ```ts twoslash [nuxt.config.ts]
344
382
  export default defineNuxtConfig({
345
383
  experimental: {
346
- sharedPrerenderData: true
347
- }
384
+ sharedPrerenderData: true,
385
+ },
348
386
  })
349
387
  ```
350
388
 
@@ -378,7 +416,7 @@ To make globals like `Buffer` work in the browser, you need to manually inject t
378
416
  ```ts
379
417
  import { Buffer } from 'node:buffer'
380
418
 
381
- globalThis.Buffer = globalThis.Buffer || Buffer
419
+ globalThis.Buffer ||= Buffer
382
420
  ```
383
421
  ::
384
422
 
@@ -395,8 +433,8 @@ You can disable this feature if it causes issues in your project.
395
433
  ```ts twoslash [nuxt.config.ts]
396
434
  export default defineNuxtConfig({
397
435
  experimental: {
398
- scanPageMeta: false
399
- }
436
+ scanPageMeta: false,
437
+ },
400
438
  })
401
439
  ```
402
440
 
@@ -407,8 +445,8 @@ Enables CookieStore support to listen for cookie updates (if supported by the br
407
445
  ```ts twoslash [nuxt.config.ts]
408
446
  export default defineNuxtConfig({
409
447
  experimental: {
410
- cookieStore: true
411
- }
448
+ cookieStore: true,
449
+ },
412
450
  })
413
451
  ```
414
452
 
@@ -423,8 +461,8 @@ Caches Nuxt build artifacts based on a hash of the configuration and source file
423
461
  ```ts twoslash [nuxt.config.ts]
424
462
  export default defineNuxtConfig({
425
463
  experimental: {
426
- buildCache: true
427
- }
464
+ buildCache: true,
465
+ },
428
466
  })
429
467
  ```
430
468
 
@@ -457,7 +495,7 @@ This option allows passing additional keys to extract from the page metadata whe
457
495
  ```vue
458
496
  <script lang="ts" setup>
459
497
  definePageMeta({
460
- foo: 'bar'
498
+ foo: 'bar',
461
499
  })
462
500
  </script>
463
501
  ```
@@ -475,7 +513,7 @@ export default defineNuxtConfig({
475
513
  })
476
514
  ```
477
515
 
478
- This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/guide/directory-structure/pages#typing-custom-metadata).
516
+ This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/3.x/guide/directory-structure/pages#typing-custom-metadata).
479
517
 
480
518
  ## normalizeComponentNames
481
519
 
@@ -485,8 +523,8 @@ you would use to auto-import the component.
485
523
  ```ts twoslash [nuxt.config.ts]
486
524
  export default defineNuxtConfig({
487
525
  experimental: {
488
- normalizeComponentNames: true
489
- }
526
+ normalizeComponentNames: true,
527
+ },
490
528
  })
491
529
  ```
492
530
 
@@ -535,8 +573,8 @@ This is enabled by default in development mode. If you need to disable this feat
535
573
  ```ts twoslash [nuxt.config.ts]
536
574
  export default defineNuxtConfig({
537
575
  experimental: {
538
- browserDevtoolsTiming: false
539
- }
576
+ browserDevtoolsTiming: false,
577
+ },
540
578
  })
541
579
  ```
542
580
 
@@ -559,8 +597,8 @@ To enable it explicitly:
559
597
  ```ts twoslash [nuxt.config.ts]
560
598
  export default defineNuxtConfig({
561
599
  experimental: {
562
- debugModuleMutation: true
563
- }
600
+ debugModuleMutation: true,
601
+ },
564
602
  })
565
603
  ```
566
604
 
@@ -577,8 +615,8 @@ Lazy hydration is enabled by default, but you can disable this feature:
577
615
  ```ts twoslash [nuxt.config.ts]
578
616
  export default defineNuxtConfig({
579
617
  experimental: {
580
- lazyHydration: false
581
- }
618
+ lazyHydration: false,
619
+ },
582
620
  })
583
621
  ```
584
622
 
@@ -595,8 +633,8 @@ This is enabled by default, so if you're experiencing resolution conflicts in ce
595
633
  ```ts twoslash [nuxt.config.ts]
596
634
  export default defineNuxtConfig({
597
635
  experimental: {
598
- templateImportResolution: false
599
- }
636
+ templateImportResolution: false,
637
+ },
600
638
  })
601
639
  ```
602
640
 
@@ -650,8 +688,8 @@ and ensures fresh data is loaded when needed, but it is possible to disable it:
650
688
  ```ts twoslash [nuxt.config.ts]
651
689
  export default defineNuxtConfig({
652
690
  experimental: {
653
- purgeCachedData: false
654
- }
691
+ purgeCachedData: false,
692
+ },
655
693
  })
656
694
  ```
657
695
 
@@ -666,8 +704,8 @@ Whether to call and use the result from `getCachedData` when refreshing data for
666
704
  ```ts twoslash [nuxt.config.ts]
667
705
  export default defineNuxtConfig({
668
706
  experimental: {
669
- granularCachedData: true
670
- }
707
+ granularCachedData: true,
708
+ },
671
709
  })
672
710
  ```
673
711
 
@@ -684,8 +722,8 @@ That means that when `immediate: false` is passed, `pending` will be `false` unt
684
722
  ```ts twoslash [nuxt.config.ts]
685
723
  export default defineNuxtConfig({
686
724
  experimental: {
687
- pendingWhenIdle: false
688
- }
725
+ pendingWhenIdle: false,
726
+ },
689
727
  })
690
728
  ```
691
729
 
@@ -710,14 +748,64 @@ If you need to disable this feature you can do so:
710
748
  ```ts twoslash [nuxt.config.ts]
711
749
  export default defineNuxtConfig({
712
750
  experimental: {
713
- entryImportMap: false
751
+ entryImportMap: false,
714
752
  },
715
- // or, better, simply tell vite your desired target
753
+ // or, better, simply tell vite your desired target
716
754
  // which nuxt will respect
717
755
  vite: {
718
756
  build: {
719
- target: 'safari13'
757
+ target: 'safari13',
720
758
  },
721
759
  },
722
760
  })
723
761
  ```
762
+
763
+ ## typescriptPlugin
764
+
765
+ Enable enhanced TypeScript developer experience with the `@dxup/nuxt` module.
766
+
767
+ This experimental plugin provides improved TypeScript integration and development tooling for better DX when working with TypeScript in Nuxt applications.
768
+
769
+ This flag is disabled by default, but you can enable this feature:
770
+
771
+ ```ts twoslash [nuxt.config.ts]
772
+ export default defineNuxtConfig({
773
+ experimental: {
774
+ typescriptPlugin: true,
775
+ },
776
+ })
777
+ ```
778
+
779
+ ::important
780
+ To use this feature, you need to:
781
+ - Have `typescript` installed as a dependency
782
+ - Configure VS Code to use your workspace TypeScript version (see [VS Code documentation](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript))
783
+ ::
784
+
785
+ ::read-more{icon="i-simple-icons-github" to="https://github.com/KazariEX/dxup" target="_blank"}
786
+ Learn more about **@dxup/nuxt**.
787
+ ::
788
+
789
+ ## viteEnvironmentApi
790
+
791
+ Enable Vite 6's new [Environment API](https://vite.dev/guide/api-environment) for improved build configuration and plugin architecture.
792
+
793
+ When you set `future.compatibilityVersion` to `5`, this feature is enabled by default. You can also enable it explicitly for testing:
794
+
795
+ ```ts twoslash [nuxt.config.ts]
796
+ export default defineNuxtConfig({
797
+ experimental: {
798
+ viteEnvironmentApi: true,
799
+ },
800
+ })
801
+ ```
802
+
803
+ The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.
804
+
805
+ ::important
806
+ Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.
807
+ ::
808
+
809
+ ::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
810
+ Learn more about Vite's Environment API.
811
+ ::
@@ -16,8 +16,8 @@ You can also pass a function that receives the path of a Vue component and retur
16
16
  ```ts [nuxt.config.ts]
17
17
  export default defineNuxtConfig({
18
18
  features: {
19
- inlineStyles: false // or a function to determine inlining
20
- }
19
+ inlineStyles: false, // or a function to determine inlining
20
+ },
21
21
  })
22
22
  ```
23
23
 
@@ -28,8 +28,8 @@ Disables rendering of Nuxt scripts and JS resource hints. Can also be configured
28
28
  ```ts [nuxt.config.ts]
29
29
  export default defineNuxtConfig({
30
30
  features: {
31
- noScripts: true
32
- }
31
+ noScripts: true,
32
+ },
33
33
  })
34
34
  ```
35
35
 
@@ -58,7 +58,7 @@ export default defineNuxtConfig({
58
58
  // To re-enable _all_ Nuxt v3 behaviour, set the following options:
59
59
  srcDir: '.',
60
60
  dir: {
61
- app: 'app'
61
+ app: 'app',
62
62
  },
63
63
  experimental: {
64
64
  scanPageMeta: 'after-resolve',
@@ -67,21 +67,21 @@ export default defineNuxtConfig({
67
67
  resetAsyncDataToUndefined: true,
68
68
  templateUtils: true,
69
69
  relativeWatchPaths: true,
70
- normalizeComponentNames: false
70
+ normalizeComponentNames: false,
71
71
  defaults: {
72
72
  useAsyncData: {
73
- deep: true
74
- }
75
- }
73
+ deep: true,
74
+ },
75
+ },
76
76
  },
77
77
  features: {
78
- inlineStyles: true
78
+ inlineStyles: true,
79
79
  },
80
80
  unhead: {
81
81
  renderSSRHeadOptions: {
82
- omitLineBreaks: false
83
- }
84
- }
82
+ omitLineBreaks: false,
83
+ },
84
+ },
85
85
  })
86
86
  ```
87
87
 
@@ -97,7 +97,7 @@ See [the original TypeScript pull request](https://github.com/microsoft/TypeScri
97
97
  ```ts [nuxt.config.ts]
98
98
  export default defineNuxtConfig({
99
99
  future: {
100
- typescriptBundlerResolution: true
101
- }
100
+ typescriptBundlerResolution: true,
101
+ },
102
102
  })
103
103
  ```
@@ -7,15 +7,15 @@ This guide helps you better understand Nuxt internals to develop new solutions a
7
7
 
8
8
  ## The Nuxt Interface
9
9
 
10
- When you start Nuxt in development mode with [`nuxt dev`](/docs/api/commands/dev) or building a production application with [`nuxt build`](/docs/api/commands/build),
10
+ When you start Nuxt in development mode with [`nuxt dev`](/docs/3.x/api/commands/dev) or building a production application with [`nuxt build`](/docs/3.x/api/commands/build),
11
11
  a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
12
- some internal state, and a powerful [hooking system](/docs/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
12
+ some internal state, and a powerful [hooking system](/docs/3.x/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
13
13
  allowing different components to communicate with each other. You can think of it as **Builder Core**.
14
14
 
15
- This context is globally available to be used with [Nuxt Kit](/docs/guide/going-further/kit) composables.
15
+ This context is globally available to be used with [Nuxt Kit](/docs/3.x/guide/going-further/kit) composables.
16
16
  Therefore only one instance of Nuxt is allowed to run per process.
17
17
 
18
- To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/guide/going-further/modules).
18
+ To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/3.x/guide/going-further/modules).
19
19
 
20
20
  For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).
21
21
 
@@ -25,42 +25,42 @@ When rendering a page in the browser or on the server, a shared context will be
25
25
  This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
26
26
  You can think of it as **Runtime Core**.
27
27
 
28
- This context can be accessed using [`useNuxtApp()`](/docs/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
28
+ This context can be accessed using [`useNuxtApp()`](/docs/3.x/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
29
29
  Global usage is possible for the browser but not on the server, to avoid sharing context between users.
30
30
 
31
- Since [`useNuxtApp`](/docs/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
31
+ Since [`useNuxtApp`](/docs/3.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/3.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
32
32
 
33
- To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/guide/directory-structure/plugins).
33
+ To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/3.x/guide/directory-structure/plugins).
34
34
 
35
- Check [Nuxt App](/docs/api/composables/use-nuxt-app) for more information about this interface.
35
+ Check [Nuxt App](/docs/3.x/api/composables/use-nuxt-app) for more information about this interface.
36
36
 
37
37
  `nuxtApp` has the following properties:
38
38
 
39
- ```js
40
- const nuxtApp = {
41
- vueApp, // the global Vue application: https://vuejs.org/api/application.html#application-api
39
+ ```ts
40
+ interface NuxtApp {
41
+ vueApp // the global Vue application: https://vuejs.org/api/application.html#application-api
42
42
 
43
- versions, // an object containing Nuxt and Vue versions
43
+ versions // an object containing Nuxt and Vue versions
44
44
 
45
45
  // These let you call and add runtime NuxtApp hooks
46
46
  // https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts#L18
47
- hooks,
48
- hook,
49
- callHook,
47
+ hooks
48
+ hook
49
+ callHook
50
50
 
51
51
  // Only accessible on server-side
52
52
  ssrContext: {
53
- url,
54
- req,
55
- res,
56
- runtimeConfig,
57
- noSSR,
58
- },
53
+ url
54
+ req
55
+ res
56
+ runtimeConfig
57
+ noSSR
58
+ }
59
59
 
60
60
  // This will be stringified and passed from server to client
61
61
  payload: {
62
- serverRendered: true,
63
- data: {},
62
+ serverRendered: true
63
+ data: {}
64
64
  state: {}
65
65
  }
66
66
 
@@ -76,6 +76,6 @@ Nuxt builds and bundles project using Node.js but also has a runtime side.
76
76
 
77
77
  While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
78
78
 
79
- `nuxt.config` and [Nuxt Modules](/docs/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/guide/directory-structure/plugins) can be used to extend runtime.
79
+ `nuxt.config` and [Nuxt Modules](/docs/3.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/3.x/guide/directory-structure/plugins) can be used to extend runtime.
80
80
 
81
- When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/guide/going-further/modules).
81
+ When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/3.x/guide/going-further/modules).