@nuxt/docs-nightly 5.0.0-29740013.7699b129 → 5.0.0-29740135.daae2228

package/1.getting-started/15.prerendering.md

@@ -40,23 +40,17 @@ deno x nuxt generate
 
 You can now deploy the `.output/public` directory to any static hosting service or preview it locally with `npx serve .output/public`.
 
+Static and prerender builds also emit `200.html` and `404.html` SPA fallbacks. See [What are 200.html and 404.html?](/docs/4.x/guide/concepts/rendering#what-are-200html-and-404html).
+
 Working of the Nitro crawler:
 
 1. Load the HTML of your application's root route (`/`), any non-dynamic pages in your `~/pages` directory, and any other routes in the `nitro.prerender.routes` array.
-2. Save the HTML and `payload.json` to the `~/.output/public/` directory to be served statically.
+2. Save the HTML and `_payload.json` to the `~/.output/public/` directory to be served statically.
 3. Find all anchor tags (`<a href="...">`) in the HTML to navigate to other routes.
 4. Repeat steps 1-3 for each anchor tag found until there are no more anchor tags to crawl.
 
 This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.
 
-### Payload Extraction
-
-Nuxt generates `_payload.json` alongside HTML for:
-- Prerendered routes (at build time)
-- ISR/SWR routes (on first request)
-
-Payloads contain serialized data from `useAsyncData` and `useFetch`. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with route rules: `'/**': { isr: true }`.
-
 ::read-more{to="/docs/4.x/api/commands/generate#nuxt-generate"}
 Read more about the `nuxt generate` command.
 ::
@@ -149,6 +143,39 @@ export default defineNuxtConfig({
 })
 ```
 
+## Payload Extraction
+
+When Nuxt renders a page on the server, it serializes the results of your data fetching ([`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch)) and app state ([`useState`](/docs/4.x/api/composables/use-state)) into a payload so the client can hydrate without re-fetching. With payload extraction enabled, Nuxt also writes this payload to a `_payload.json` file alongside the route's HTML:
+
+- Prerendered routes generate their payload file at build time.
+- Routes using [ISR or SWR caching](/docs/4.x/guide/concepts/rendering#hybrid-rendering) generate their payload file when the route is first rendered, even on a hybrid (non-static) site.
+
+During client-side navigation, Nuxt fetches the `_payload.json` file for the destination route and reuses the extracted data instead of running the data fetching again in the browser.
+
+You can control this behavior with the [`experimental.payloadExtraction`](/docs/4.x/api/nuxt-config#payloadextraction) option:
+
+- `'client'` - The payload is inlined in the HTML for the initial render and extracted to `_payload.json` files for client-side navigation. There is no extra network request on first load.
+- `true` - The payload is extracted to a separate `_payload.json` file for both the initial render and client-side navigation. The HTML is smaller and the payload file can be cached by a CDN, at the cost of one extra request on first load.
+- `false` - Payload extraction is disabled. The payload is always inlined in the HTML and no `_payload.json` files are generated.
+
+The default is `true`, or `'client'` when `compatibilityVersion: 5` is set. It is forced to `false` when `ssr: false` is set.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    payloadExtraction: 'client',
+  },
+})
+```
+
+A few practical consequences to be aware of:
+
+- On a fully static site, client-side navigation reuses the data captured at build time, so data can be stale until the next rebuild.
+- For ISR/SWR routes, CDNs can cache payload files alongside the HTML, improving client-side navigation performance for cached routes. Dynamic routes like `pages/[...slug].vue` can opt in with glob patterns such as `'/**': { isr: true }`.
+- Payloads are serialized with [devalue](https://github.com/Rich-Harris/devalue), so custom types (such as class instances) need payload plugins with custom reducers and revivers to survive the round trip.
+
+:read-more{title="Payload reducers and revivers" to="/docs/4.x/api/composables/use-nuxt-app#payload"}
+
 ## Runtime Prerender Configuration
 
 ### `prerenderRoutes`

package/1.getting-started/16.deployment.md

@@ -77,9 +77,11 @@ By default, the workload gets distributed to the workers with the round robin st
 
 There are two ways to deploy a Nuxt application to any static hosting services:
 
-- Static site generation (SSG) with `ssr: true` pre-renders routes of your application at build time. (This is the default behavior when running `nuxt generate`.) It will also generate `/200.html` and `/404.html` single-page app fallback pages, which can render dynamic routes or 404 errors on the client (though you may need to configure this on your static host).
+- Static site generation (SSG) with `ssr: true` pre-renders routes of your application at build time. (This is the default behavior when running `nuxt generate`.) It will also generate `/200.html` and `/404.html` single-page app fallback pages, which can render dynamic routes or 404 errors on the client (though you may need to configure this on your static host). See [What are 200.html and 404.html?](/docs/4.x/guide/concepts/rendering#what-are-200html-and-404html).
 - Alternatively, you can prerender your site with `ssr: false` (static single-page app). This will produce HTML pages with an empty `<div id="__nuxt"></div>` where your Vue app would normally be rendered. You will lose many SEO benefits of prerendering your site, so it is suggested instead to use [`<ClientOnly>`](/docs/4.x/api/components/client-only) to wrap the portions of your site that cannot be server rendered (if any).
 
+Prerendered routes also emit `_payload.json` files with the data captured at build time, which Nuxt reuses during client-side navigation. Read more about [payload extraction](/docs/4.x/getting-started/prerendering#payload-extraction).
+
 ### Static Fallback Pages
 
 Nuxt can generate two fallback pages for static hosts:

package/3.guide/1.concepts/1.rendering.md

@@ -124,7 +124,14 @@ This will produce three files:
 - `200.html`
 - `404.html`
 
-The `200.html` file is intended for static hosts that need a success-status fallback for client-side routing. The `404.html` file is intended for static hosts that serve a not-found page while preserving a 404 status. Which file you should use depends on your hosting provider's fallback or rewrite settings.
+#### What are 200.html and 404.html?
+
+Static hosts need an HTML shell for client-side routes and missing paths. Nuxt emits two SPA fallbacks for that:
+
+- **`200.html`**. Serve this for unmatched paths when you want the client router to handle the URL.
+- **`404.html`**. Serve this when the host should keep a 404 status and still load your app.
+
+`nuxt generate` and `nuxt build --prerender` write these into `.output/public/`. A plain `nuxt build` without prerender does not. With hybrid route rules, add the fallbacks with route rules or run a prerender build if you need them. Point your host at the file your provider expects.
 
 #### Skipping Client Fallback Generation
 
@@ -194,7 +201,7 @@ The different properties you can use are the following:
 - `appMiddleware: string | string[] | Record<string, boolean>`{lang=ts} - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)
 
 ::note
-Routes using `isr` or `swr` also generate `_payload.json` files alongside HTML. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with glob patterns: `'/**': { isr: true }`.
+Routes using `isr` or `swr` also generate `_payload.json` files alongside HTML. Client-side navigation loads these cached payloads instead of re-fetching data. Read more about [payload extraction](/docs/4.x/getting-started/prerendering#payload-extraction).
 ::
 
 Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).

package/3.guide/6.going-further/1.experimental-features.md

@@ -208,35 +208,23 @@ export default defineNuxtConfig({
 
 Controls how payload data is delivered for prerendered and cached (ISR/SWR) pages.
 
-- `'client'` - Payload is inlined in HTML for the initial server render, and extracted to `_payload.json` files for client-side navigation. This avoids a separate network request on initial load while still enabling efficient client-side navigation.
+- `'client'` - Payload is inlined in HTML for the initial server render, and extracted to `_payload.json` files for client-side navigation.
 - `true` - Payload is extracted to a separate `_payload.json` file for both the initial server render and client-side navigation.
 - `false` - Payload extraction is disabled entirely. Payload is always inlined in HTML and no `_payload.json` files are generated.
 
-The default is `true`, or `'client'` when `compatibilityVersion: 5` is set.
+The default is `true`, or `'client'` when `compatibilityVersion: 5` is set. It is forced to `false` when `ssr: false` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    // Inline payload in HTML, extract for client-side navigation only
     payloadExtraction: 'client',
   },
 })
 ```
 
-Payload extraction also works for routes using ISR (Incremental Static Regeneration) or SWR (Stale-While-Revalidate) caching strategies. This allows CDNs to cache payload files alongside HTML, improving client-side navigation performance for cached routes.
-
-```ts twoslash [nuxt.config.ts]
-export default defineNuxtConfig({
-  experimental: {
-    payloadExtraction: 'client',
-  },
-  routeRules: {
-    // Payload files will be generated for these cached routes
-    '/products/**': { isr: 3600 },
-    '/blog/**': { swr: true },
-  },
-})
-```
+::read-more{to="/docs/4.x/getting-started/prerendering#payload-extraction"}
+Read more about payload extraction and the consequences of each mode.
+::
 
 ## clientNodePlaceholder
 

package/4.api/1.components/4.nuxt-link.md

@@ -340,7 +340,7 @@ export default defineNuxtLink({
 })
 ```
 
-You can then use `<MyNuxtLink />` component as usual with your new defaults.
+The component is auto-imported by its file name, so you can use `<MyNuxtLink />` as usual with your new defaults. `componentName` only sets the component's internal name (as shown in Vue DevTools); it does not change how the component is used in templates.
 
 ### `defineNuxtLink` Signature
 
@@ -361,7 +361,7 @@ interface NuxtLinkOptions {
 function defineNuxtLink (options: NuxtLinkOptions): Component {}
 ```
 
-- `componentName`: A name for the component. Default is `NuxtLink`.
+- `componentName`: The component's internal name, as shown in Vue DevTools. It does not change the name used in templates (that comes from the component's file name). Default is `NuxtLink`.
 - `externalRelAttribute`: A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable
 - `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkActiveClass-). Defaults to Vue Router's default (`"router-link-active"`)
 - `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkExactActiveClass-). Defaults to Vue Router's default (`"router-link-exact-active"`)

package/4.api/2.composables/use-cookie.md

@@ -64,7 +64,7 @@ Most of the options will be directly passed to the [cookie](https://github.com/j
 | `refresh` :badge[v4.4]{color="info" size="xs" class="align-middle"} | `boolean`              | `false`                                                        | If `true`, the cookie expiration will be refreshed on every explicit write (e.g. `cookie.value = cookie.value`), even if the value itself hasn’t changed. Note: the expiration is not refreshed automatically — you must assign to `.value` to trigger it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `readonly`    | `boolean`              | `false`                                                        | If `true`, disables writing to the cookie.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `maxAge`      | `number`               | `undefined`                                                    | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set.                                                                                                                                                                                                                                                                                                                                                                                   |
-| `expires`     | `Date`                 | `undefined`                                                    | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://datatracker.ietf.org/doc/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
+| `expires`     | `Date \| (() => Date \| undefined)` | `undefined`                                                    | Expiration date for the cookie, or a getter that returns one. When a function is provided, it is evaluated on every cookie write, so the expiration can be refreshed when the value is re-set. Returning `undefined` creates a session cookie. The getter should be pure (no side effects). By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://datatracker.ietf.org/doc/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
 | `httpOnly`    | `boolean`              | `false`                                                        | Sets the HttpOnly attribute. <br/> **Note:** Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `secure`      | `boolean`              | `false`                                                        | Sets the [`Secure` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5). <br/>**Note:** Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.                                                                                                                                                                                                                                                                                                                |
 | `partitioned` | `boolean`              | `false`                                                        | Sets the [`Partitioned` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1). <br/>**Note:** This is an attribute that has not yet been fully standardized, and may change in the future. <br/>This also means many clients may ignore this attribute until they understand it.<br/>More information can be found in the [proposal](https://github.com/privacycg/CHIPS).                                                                                                                                                                                                            |
@@ -187,6 +187,22 @@ session.value = 'active'
 </template>
 ```
 
+### Dynamic Expiration with a Getter
+
+Use a function for `expires` when you want a fresh expiration date every time the cookie is written (for example, sliding sessions or tokens):
+
+```vue
+<script setup lang="ts">
+const token = useCookie('token', {
+  // Re-evaluated on every write — keep this getter pure
+  expires: () => new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now
+})
+
+// Assigning a new value also refreshes the cookie expiration
+token.value = 'new-token'
+</script>
+```
+
 ### Cookies in API Routes
 
 You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29740013.7699b129",
+  "version": "5.0.0-29740135.daae2228",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",