docs: add experimental features page (#21617)

This commit is contained in:
Hebilicious 2023-06-21 01:17:07 +07:00 committed by GitHub
parent 5216e11ca9
commit 2c9ac8dd80
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -0,0 +1,227 @@
---
title: "Experimental Features"
description: "Nuxt experimental features needs to be enabled manually."
---
# Experimental Features
The Nuxt experimental features can be enabled in the Nuxt configuration file.
Internally, Nuxt use `@nuxt/schema` to define these experimentatl features. You can refer to the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
::alert{type=info icon=💡}
Note that these features are experimental and could be removed or modified in the future.
::
## asyncEntry
Enables generation of an async entry point for the Vue bundle, aiding module federation support.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { asyncEntry: true } })
```
## reactivityTransform
Enables Vue's reactivity transform. Note that this feature has been marked as deprecated in Vue 3.3 and is planned to be removed from core in Vue 3.4.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { reactivityTransform: true } })
```
::ReadMore{link="docs/getting-started/configuration#enabling-experimental-vue-features"}
## externalVue
Externalizes `vue`, `@vue/*` and `vue-router` when building.
*Enabled by default.*
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { externalVue: true } })
```
::alert{type=warning icon=⚠️}
This feature will likely be removed in Nuxt 3.6.
::
## treeshakeClientOnly
Tree shakes contents of client-only components from server bundle.
*Enabled by default.*
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { treeshakeClientOnly: true } })
```
## emitRouteChunkError
Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a hard reload of the new route when a chunk fails to load.
You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { emitRouteChunkError: 'automatic' } }) // or 'manual' or false
```
## restoreState
Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual `reloadNuxtApp()` call.
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.
::alert{type=warning icon=⚠️}
Consider carefully before enabling this as it can cause unexpected behavior,
and consider providing explicit keys to `useState` as auto-generated keys may not match across builds.
::
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { restoreState: true } })
```
## inlineSSRStyles
Inlines styles when rendering HTML. This is currently available only when using Vite.
You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { inlineSSRStyles: true } }) // or a function to determine inlining
```
## noScripts
Disables rendering of Nuxt scripts and JS resource hints. Can also be configured granularly within `routeRules`.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { noScripts: true } })
```
## renderJsonPayloads
Allows rendering of JSON payloads with support for revivifying complex types.
*Enabled by default.*
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { renderJsonPayloads: true } })
```
## noVueServer
Disables Vue server renderer endpoint within Nitro.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { noVueServer: true } })
```
## payloadExtraction
Enables extraction of payloads of pages generated with `nuxt generate`.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { payloadExtraction: true } })
```
## clientFallback
Enables the experimental `<NuxtClientFallback>` component for rendering content on the client if there's an error in SSR.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { clientFallback: true } })
```
## crossOriginPrefetch
Enables cross-origin prefetch using the Speculation Rules API.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { crossOriginPrefetch: true } })
```
## viewTransition
Enables View Transition API integration with client-side router.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { viewTransition: true } })
```
::ReadMore{link="docs/getting-started/transitions#view-transitions-api-experimental"}
## writeEarlyHints
Enables writing of early hints when using node server.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { writeEarlyHints: true } })
```
## componentIslands
Enables experimental component islands support with `<NuxtIsland>` and `.island.vue` files.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { componentIslands: true } })
```
::ReadMore{link="docs/guide/directory-structure/components#server-components"}
You can follow the server components roadmap on [GitHub](https://github.com/nuxt/nuxt/issues/19772).
## configSchema
Enables config schema support.
*Enabled by default.*
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { configSchema: true } })
```
## polyfillVueUseHead
Adds a compatibility layer for modules, plugins, or user code relying on the old `@vueuse/head` API.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { polyfillVueUseHead: false } })
```
## respectNoSSRHeader
Allow disabling Nuxt SSR responses by setting the `x-nuxt-no-ssr` header.
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { respectNoSSRHeader: false } })
```
## localLayerAliases
Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.
*Enabled by default.*
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { localLayerAliases: true } })
```
## typedPages
Enable the new experimental typed router using [unplugin-vue-router](https://github.com/posva/unplugin-vue-router).
```ts [nuxt.config.ts]
export defineNuxtConfig({ experimental: { typedPages: false } })
```
Out of the box, this will enable typed usage of `navigateTo`, `<NuxtLink>`, `router.push()` and more.
You can even get typed params within a page by using `const route = useRoute('route-name')`.
## watcher
Set an alternative watcher that will be used as the watching service for Nuxt.
Nuxt uses `chokidar-granular` by default, which will ignore top-level directories
(like `node_modules` and `.git`) that are excluded from watching.
You can set this instead to `parcel` to use `@parcel/watcher`, which may improve
performance in large projects or on Windows platforms.
You can also set this to `chokidar` to watch all files in your source directory.
```ts [nuxt.config.ts]
export defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
}
})
```