Skip to content

Commit b438d44

Browse files
danielroedanielroe
committed
docs: remove duplicated documentation from nuxt.config page
resolves #33310
1 parent 110962e commit b438d44

File tree

4 files changed

+226
-644
lines changed

4 files changed

+226
-644
lines changed

‎docs/2.guide/3.going-further/1.experimental-features.md‎

Lines changed: 179 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,36 @@ Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You
1111
Note that these features are experimental and could be removed or modified in the future.
1212
::
1313

14+
## alwaysRunFetchOnKeyChange
15+
16+
Whether to run `useFetch` when the key changes, even if it is set to `immediate: false` and it has not been triggered yet.
17+
18+
`useFetch` and `useAsyncData` will always run when the key changes if `immediate: true` or if it has been already triggered.
19+
20+
This flag is disabled by default, but you can enable this feature:
21+
22+
```ts twoslash [nuxt.config.ts]
23+
export default defineNuxtConfig({
24+
experimental: {
25+
alwaysRunFetchOnKeyChange: true,
26+
},
27+
})
28+
```
29+
30+
## appManifest
31+
32+
Use app manifests to respect route rules on client-side.
33+
34+
This flag is enabled by default, but you can disable this feature:
35+
36+
```ts twoslash [nuxt.config.ts]
37+
export default defineNuxtConfig({
38+
experimental: {
39+
appManifest: false,
40+
},
41+
})
42+
```
43+
1444
## asyncContext
1545

1646
Enable native async context to be accessible for nested composables in Nuxt and in Nitro. This opens the possibility to use composables inside async composables and reduce the chance to get the `Nuxt instance is unavailable` error.
@@ -43,12 +73,12 @@ export default defineNuxtConfig({
4373

4474
Externalizes `vue`, `@vue/*` and `vue-router` when building.
4575

46-
*Enabled by default.*
76+
This flag is enabled by default, but you can disable this feature:
4777

4878
```ts twoslash [nuxt.config.ts]
4979
export default defineNuxtConfig({
5080
experimental: {
51-
externalVue: true,
81+
externalVue: false,
5282
},
5383
})
5484
```
@@ -61,7 +91,9 @@ This feature will likely be removed in a near future.
6191

6292
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.
6393

64-
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/4.x/guide/directory-structure/app/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.
94+
By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
95+
96+
Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for 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/4.x/guide/directory-structure/app/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.
6597

6698
You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
6799

@@ -73,6 +105,20 @@ export default defineNuxtConfig({
73105
})
74106
```
75107

108+
## enforceModuleCompatibility
109+
110+
Whether Nuxt should throw an error (and fail to load) if a Nuxt module is incompatible.
111+
112+
This feature is disabled by default.
113+
114+
```ts twoslash [nuxt.config.ts]
115+
export default defineNuxtConfig({
116+
experimental: {
117+
enforceModuleCompatibility: true,
118+
},
119+
})
120+
```
121+
76122
## restoreState
77123

78124
Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/4.x/api/utils/reload-nuxt-app) call.
@@ -116,12 +162,12 @@ Read more in `defineRouteRules` utility.
116162

117163
Allows rendering of JSON payloads with support for revivifying complex types.
118164

119-
*Enabled by default.*
165+
This flag is enabled by default, but you can disable this feature:
120166

121167
```ts twoslash [nuxt.config.ts]
122168
export default defineNuxtConfig({
123169
experimental: {
124-
renderJsonPayloads: true,
170+
renderJsonPayloads: false,
125171
},
126172
})
127173
```
@@ -138,6 +184,20 @@ export default defineNuxtConfig({
138184
})
139185
```
140186

187+
## parseErrorData
188+
189+
Whether to parse `error.data` when rendering a server error page.
190+
191+
This flag is enabled by default, but you can disable this feature:
192+
193+
```ts twoslash [nuxt.config.ts]
194+
export default defineNuxtConfig({
195+
experimental: {
196+
parseErrorData: false,
197+
},
198+
})
199+
```
200+
141201
## payloadExtraction
142202

143203
Enables extraction of payloads of pages generated with `nuxt generate`.
@@ -230,12 +290,12 @@ You can follow the server components roadmap on GitHub.
230290

231291
Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
232292

233-
*Enabled by default.*
293+
This flag is enabled by default, but you can disable this feature:
234294

235295
```ts twoslash [nuxt.config.ts]
236296
export default defineNuxtConfig({
237297
experimental: {
238-
localLayerAliases: true,
298+
localLayerAliases: false,
239299
},
240300
})
241301
```
@@ -352,10 +412,12 @@ export default defineNuxtConfig({
352412

353413
Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
354414

415+
This flag is enabled by default, but you can disable this feature:
416+
355417
```ts twoslash [nuxt.config.ts]
356418
export default defineNuxtConfig({
357419
experimental: {
358-
cookieStore: true,
420+
cookieStore: false,
359421
},
360422
})
361423
```
@@ -368,6 +430,10 @@ Read more about the **CookieStore**.
368430

369431
Caches Nuxt build artifacts based on a hash of the configuration and source files.
370432

433+
This only works for source files within `srcDir` and `serverDir` for the Vue/Nitro parts of your app.
434+
435+
This flag is disabled by default, but you can enable it:
436+
371437
```ts twoslash [nuxt.config.ts]
372438
export default defineNuxtConfig({
373439
experimental: {
@@ -396,6 +462,20 @@ In addition, any changes to files within `srcDir` will trigger a rebuild of the
396462
A maximum of 10 cache tarballs are kept.
397463
::
398464

465+
## checkOutdatedBuildInterval
466+
467+
Set the time interval (in ms) to check for new builds. Disabled when `experimental.appManifest` is `false`.
468+
469+
Set to `false` to disable.
470+
471+
```ts twoslash [nuxt.config.ts]
472+
export default defineNuxtConfig({
473+
experimental: {
474+
checkOutdatedBuildInterval: 3600000, // 1 hour, or false to disable
475+
},
476+
})
477+
```
478+
399479
## extraPageMetaExtractionKeys
400480

401481
The `definePageMeta()` macro is a useful way to collect build-time meta about pages. Nuxt itself provides a set list of supported keys which is used to power some of the internal features such as redirects, page aliases and custom paths.
@@ -425,6 +505,22 @@ export default defineNuxtConfig({
425505

426506
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/4.x/guide/directory-structure/app/pages#typing-custom-metadata).
427507

508+
## navigationRepaint
509+
510+
Wait for a single animation frame before navigation, which gives an opportunity for the browser to repaint, acknowledging user interaction.
511+
512+
It can reduce INP when navigating on prerendered routes.
513+
514+
This flag is enabled by default, but you can disable this feature:
515+
516+
```ts twoslash [nuxt.config.ts]
517+
export default defineNuxtConfig({
518+
experimental: {
519+
navigationRepaint: false,
520+
},
521+
})
522+
```
523+
428524
## normalizeComponentNames
429525

430526
Nuxt updates auto-generated Vue component names to match the full component name you would use to auto-import the component.
@@ -537,9 +633,11 @@ Read more about lazy hydration.
537633

538634
## templateImportResolution
539635

540-
Controls how imports in Nuxt templates are resolved. By default, Nuxt attempts to resolve imports in templates relative to the module that added them.
636+
Disable resolving imports into Nuxt templates from the path of the module that added the template.
637+
638+
By default, Nuxt attempts to resolve imports in templates relative to the module that added them. Setting this to `false` disables this behavior, which may be useful if you're experiencing resolution conflicts in certain environments.
541639

542-
This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior:
640+
This flag is enabled by default, but you can disable this feature:
543641

544642
```ts twoslash [nuxt.config.ts]
545643
export default defineNuxtConfig({
@@ -553,6 +651,22 @@ export default defineNuxtConfig({
553651
See PR #31175 for implementation details.
554652
::
555653

654+
## templateRouteInjection
655+
656+
By default the route object returned by the auto-imported `useRoute()` composable is kept in sync with the current page in view in `<NuxtPage>`. This is not true for `vue-router`'s exported `useRoute` or for the default `$route` object available in your Vue templates.
657+
658+
By enabling this option a mixin will be injected to keep the `$route` template object in sync with Nuxt's managed `useRoute()`.
659+
660+
This flag is enabled by default, but you can disable this feature:
661+
662+
```ts twoslash [nuxt.config.ts]
663+
export default defineNuxtConfig({
664+
experimental: {
665+
templateRouteInjection: false,
666+
},
667+
})
668+
```
669+
556670
## decorators
557671

558672
This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
@@ -591,10 +705,40 @@ const value = new SomeClass().someMethod()
591705
// this will return 'decorated'
592706
```
593707

708+
## defaults
709+
710+
This allows specifying the default options for core Nuxt components and composables.
711+
712+
These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
713+
714+
```ts twoslash [nuxt.config.ts]
715+
export default defineNuxtConfig({
716+
experimental: {
717+
defaults: {
718+
nuxtLink: {
719+
componentName: 'NuxtLink',
720+
prefetch: true,
721+
prefetchOn: {
722+
visibility: true,
723+
},
724+
},
725+
useAsyncData: {
726+
deep: true,
727+
errorValue: 'null',
728+
value: 'null',
729+
},
730+
},
731+
},
732+
})
733+
```
734+
594735
## purgeCachedData
595736

596-
Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks
597-
and ensures fresh data is loaded when needed, but it is possible to disable it:
737+
Whether to clean up Nuxt static and asyncData caches on route navigation.
738+
739+
Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks and ensures fresh data is loaded when needed, but it is possible to disable it.
740+
741+
This flag is enabled by default, but you can disable this feature:
598742

599743
```ts twoslash [nuxt.config.ts]
600744
export default defineNuxtConfig({
@@ -612,10 +756,12 @@ See PR #31379 for implementation details.
612756

613757
Whether to call and use the result from `getCachedData` when refreshing data for `useAsyncData` and `useFetch` (whether by `watch`, `refreshNuxtData()`, or a manual `refresh()` call.
614758

759+
This flag is enabled by default, but you can disable this feature:
760+
615761
```ts twoslash [nuxt.config.ts]
616762
export default defineNuxtConfig({
617763
experimental: {
618-
granularCachedData: true,
764+
granularCachedData: false,
619765
},
620766
})
621767
```
@@ -624,16 +770,33 @@ export default defineNuxtConfig({
624770
See PR #31373 for implementation details.
625771
::
626772

773+
## headNext
774+
775+
Use head optimisations:
776+
777+
- Add the capo.js head plugin in order to render tags in of the head in a more performant way.
778+
- Uses the hash hydration plugin to reduce initial hydration
779+
780+
This flag is enabled by default, but you can disable this feature:
781+
782+
```ts twoslash [nuxt.config.ts]
783+
export default defineNuxtConfig({
784+
experimental: {
785+
headNext: false,
786+
},
787+
})
788+
```
789+
627790
## pendingWhenIdle
628791

629-
If set to `false`, the `pending` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` will be a computed property that is `true` only when `status` is also pending.
792+
For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.
630793

631-
That means that when `immediate: false` is passed, `pending` will be `false` until the first request is made.
794+
This flag is disabled by default, but you can enable this feature:
632795

633796
```ts twoslash [nuxt.config.ts]
634797
export default defineNuxtConfig({
635798
experimental: {
636-
pendingWhenIdle: false,
799+
pendingWhenIdle: true,
637800
},
638801
})
639802
```

0 commit comments

Comments
 (0)