docs: add experimental features page (#21617)

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

@@ -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
+    } 
+}) 
+```