@nuxt/docs-nightly 4.6.0-29776167.796cdae2 → 4.6.0-29778602.bfddf2f0

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.
@@ -286,7 +286,7 @@ This is an experimental option and you should refer to the Vite documentation an
286
286
 
287
287
  ## Single File Components (SFC) Styling
288
288
 
289
- One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://github.com/Tahul/pinceau).
289
+ One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have a fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://github.com/Tahul/pinceau).
290
290
 
291
291
  You can refer to the [Vue docs](https://vuejs.org/api/sfc-css-features) for a comprehensive reference about styling components in SFC.
292
292
 
@@ -362,7 +362,7 @@ Refer to the [Vue docs](https://vuejs.org/guide/essentials/class-and-style) for
362
362
 
363
363
  ### Dynamic Styles With `v-bind`
364
364
 
365
- You can reference JavaScript variable and expression within your style blocks with the v-bind function.
365
+ You can reference JavaScript variables and expressions within your style blocks with the v-bind function.
366
366
  The binding will be dynamic, meaning that if the variable value changes, the style will be updated.
367
367
 
368
368
  ```vue
@@ -147,7 +147,7 @@ const title = ref('Hello World')
147
147
  </template>
148
148
  ```
149
149
 
150
- It's suggested to wrap your components in either a `<Head>` or `<Html>` components as tags will be deduped more intuitively.
150
+ It's suggested to wrap your components in either a `<Head>` or `<Html>` component as tags will be deduped more intuitively.
151
151
 
152
152
  ::warning
153
153
  If you need to duplicate tags across client-server boundaries, apply a `key` attribute on the `<Head>` component.
@@ -25,7 +25,7 @@ export default defineNuxtConfig({
25
25
  ```
26
26
 
27
27
  ::note
28
- If you are changing layouts as well as page, the page transition you set here will not run. Instead, you should set a [layout transition](/docs/4.x/getting-started/transitions#layout-transitions).
28
+ If you are changing layouts as well as pages, the page transition you set here will not run. Instead, you should set a [layout transition](/docs/4.x/getting-started/transitions#layout-transitions).
29
29
  ::
30
30
 
31
31
  To start adding transition between your pages, add the following CSS to your [`app.vue`](/docs/4.x/directory-structure/app/app):
@@ -389,7 +389,7 @@ const next = computed(() => '/' + (id.value + 1))
389
389
 
390
390
  ::
391
391
 
392
- The page now applies the `slide-left` transition when going to the next id and `slide-right` for the previous:
392
+ The page now applies the `slide-left` transition when going to the next id and `slide-right` for the previous one:
393
393
 
394
394
  <video controls class="rounded" poster="https://res.cloudinary.com/nuxt/video/upload/v1665069410/nuxt3/nuxt-dynamic-page-transitions.jpg">
395
395
  <source src="https://res.cloudinary.com/nuxt/video/upload/v1665069410/nuxt3/nuxt-dynamic-page-transitions.mp4" type="video/mp4">
@@ -52,7 +52,7 @@ async function handleFormSubmit () {
52
52
  </template>
53
53
  ```
54
54
 
55
- In the example above, `useFetch` would make sure that the request would occur in the server and is properly forwarded to the browser. `$fetch` has no such mechanism and is a better option to use when the request is solely made from the browser.
55
+ In the example above, `useFetch` would make sure that the request would occur on the server and is properly forwarded to the browser. `$fetch` has no such mechanism and is a better option to use when the request is solely made from the browser.
56
56
 
57
57
  ### Suspense
58
58
 
@@ -180,7 +180,7 @@ It's developer experience sugar for the most common use case. (You can find out
180
180
 
181
181
  :video-accordion{title="Watch a video from Alexander Lichter to dig deeper into the difference between useFetch and useAsyncData" videoId="0X-aOpSGabA"}
182
182
 
183
- There are some cases when using the [`useFetch`](/docs/4.x/api/composables/use-fetch) composable is not appropriate, for example when a CMS or a third-party provide their own query layer. In this case, you can use [`useAsyncData`](/docs/4.x/api/composables/use-async-data) to wrap your calls and still keep the benefits provided by the composable.
183
+ There are some cases when using the [`useFetch`](/docs/4.x/api/composables/use-fetch) composable is not appropriate, for example when a CMS or a third-party provides their own query layer. In this case, you can use [`useAsyncData`](/docs/4.x/api/composables/use-async-data) to wrap your calls and still keep the benefits provided by the composable.
184
184
 
185
185
  ```vue [app/pages/users.vue]
186
186
  <script setup lang="ts">
@@ -576,7 +576,7 @@ If you need to force a refresh when other reactive values change, you can also [
576
576
 
577
577
  ### Not immediate
578
578
 
579
- The `useFetch` composable will start fetching data the moment is invoked. You may prevent this by setting `immediate: false`, for example, to wait for user interaction.
579
+ The `useFetch` composable will start fetching data the moment it is invoked. You may prevent this by setting `immediate: false`, for example, to wait for user interaction.
580
580
 
581
581
  With that, you will need both the `status` to handle the fetch lifecycle, and `execute` to start the data fetch.
582
582
 
@@ -59,7 +59,7 @@ You cannot currently define a server-side handler for these errors, but can rend
59
59
 
60
60
  You might encounter chunk loading errors due to a network connectivity failure or a new deployment (which invalidates your old, hashed JS chunk URLs). Nuxt provides built-in support for handling chunk loading errors by performing a hard reload when a chunk fails to load during route navigation.
61
61
 
62
- You can change this behavior by setting `experimental.emitRouteChunkError` to `false` (to disable hooking into these errors at all) or to `manual` if you want to handle them yourself. If you want to handle chunk loading errors manually, you can check out the [the automatic implementation](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/plugins/chunk-reload.client.ts) for ideas.
62
+ You can change this behavior by setting `experimental.emitRouteChunkError` to `false` (to disable hooking into these errors at all) or to `manual` if you want to handle them yourself. If you want to handle chunk loading errors manually, you can check out the [automatic implementation](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/plugins/chunk-reload.client.ts) for ideas.
63
63
 
64
64
  ## Error Page
65
65
 
@@ -82,7 +82,7 @@ export default defineNuxtConfig({
82
82
  ```
83
83
 
84
84
  ::read-more{to="/docs/4.x/guide/concepts/rendering#hybrid-rendering"}
85
- Learn about all available route rules are available to customize the rendering mode of your routes.
85
+ Learn about all the route rules available to customize the rendering mode of your routes.
86
86
  ::
87
87
 
88
88
  In addition, there are some route rules (for example, `ssr`, `appMiddleware`, and `noScripts`) that are Nuxt specific to change the behavior when rendering your pages to HTML.
@@ -42,7 +42,7 @@ You can now deploy the `.output/public` directory to any static hosting service
42
42
 
43
43
  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).
44
44
 
45
- Working of the Nitro crawler:
45
+ How the Nitro crawler works:
46
46
 
47
47
  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.
48
48
  2. Save the HTML and `_payload.json` to the `~/.output/public/` directory to be served statically.
@@ -38,6 +38,20 @@ It respects the following runtime environment variables:
38
38
  - `NITRO_HOST` or `HOST` (defaults to `'0.0.0.0'`)
39
39
  - `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
40
40
 
41
+ ### Serving the Same Build at Multiple Paths
42
+
43
+ For a normal subpath deployment, set [`app.baseURL`](/docs/4.x/api/nuxt-config#baseurl) or the `NUXT_APP_BASE_URL` environment variable.
44
+
45
+ If a reverse proxy deliberately exposes the same rendered page at multiple public paths, Nuxt may replace the browser URL with the path used for server rendering during hydration. You can keep the browser URL by removing the rendered path from the payload in a server plugin:
46
+
47
+ ```ts [app/plugins/preserve-proxy-url.server.ts]
48
+ export default defineNuxtPlugin((nuxtApp) => {
49
+ delete nuxtApp.payload.path
50
+ })
51
+ ```
52
+
53
+ Use this only when the proxy already handles assets and routing for every public path. Without the rendered path, Nuxt cannot correct a genuine mismatch between the requested URL and the server-rendered route.
54
+
41
55
  ### PM2
42
56
 
43
57
  [PM2](https://pm2.keymetrics.io/) (Process Manager 2) is a fast and easy solution for hosting your Nuxt application on your server or VM.
@@ -99,6 +113,8 @@ export default defineNuxtConfig({
99
113
  })
100
114
  ```
101
115
 
116
+ By default both fallbacks are empty shells. Set [`experimental.prerenderErrorPages`](/docs/4.x/guide/concepts/rendering#server-rendering-the-error-page) to server-render your `error.vue` into `404.html` at build time.
117
+
102
118
  Some providers use `200.html`, some use `404.html`, and some let you configure both. Check your hosting provider's static fallback or rewrite settings after deployment.
103
119
 
104
120
  :read-more{title="Nuxt prerendering" to="/docs/4.x/getting-started/prerendering"}
@@ -121,7 +137,7 @@ Nuxt can be deployed to several cloud providers with a minimal amount of configu
121
137
 
122
138
  ## Presets
123
139
 
124
- In addition to Node.js servers and static hosting services, a Nuxt project can be deployed with several well-tested presets and minimal amount of configuration.
140
+ In addition to Node.js servers and static hosting services, a Nuxt project can be deployed with several well-tested presets and a minimal amount of configuration.
125
141
 
126
142
  You can explicitly set the desired preset in the [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file:
127
143
 
@@ -93,7 +93,7 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
93
93
  3. If your Nuxt-environment tests live outside `test/nuxt/`, see [TypeScript Support in Tests](#typescript-support-in-tests) to add them to the TypeScript context.
94
94
 
95
95
  ::tip
96
- When importing `@nuxt/test-utils` in your vitest config, It is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.
96
+ When importing `@nuxt/test-utils` in your vitest config, it is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.
97
97
  > i.e., `vitest.config.m{ts,js}`.
98
98
  ::
99
99
 
@@ -831,7 +831,7 @@ We provide built-in support using Playwright within `@nuxt/test-utils`, either p
831
831
 
832
832
  #### `createPage(url)`
833
833
 
834
- Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available from [in the Playwright documentation](https://playwright.dev/docs/api/class-page).
834
+ Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available in the [Playwright documentation](https://playwright.dev/docs/api/class-page).
835
835
 
836
836
  ```ts twoslash
837
837
  import { createPage } from '@nuxt/test-utils/e2e'
@@ -67,6 +67,7 @@ When you set your `future.compatibilityVersion` to `5`, defaults throughout your
67
67
  - **Stricter side-effect imports**: The generated `tsconfig.json` enables [`noUncheckedSideEffectImports`](/docs/4.x/getting-started/upgrade#stricter-side-effect-imports) to match the TypeScript 7 default
68
68
  - **Vue Options API disabled**: The [Options API is compiled out of the client bundle](/docs/4.x/getting-started/upgrade#vue-options-api-disabled-by-default) to reduce its size
69
69
  - **Typed pages**: [`experimental.typedPages`](/docs/4.x/getting-started/upgrade#typed-pages-enabled-by-default) is enabled by default for type-checked routing
70
+ - **TypeScript `baseUrl` ignored**: Generated TypeScript configurations [no longer use `compilerOptions.baseUrl`](/docs/4.x/getting-started/upgrade#typescript-baseurl-is-ignored) to resolve Nuxt aliases
70
71
  - Other Nuxt 5 improvements and changes as they become available
71
72
 
72
73
  ::note
@@ -550,6 +551,40 @@ export default defineNuxtConfig({
550
551
  })
551
552
  ```
552
553
 
554
+ ### TypeScript `baseUrl` Is Ignored
555
+
556
+ 🚦 **Impact Level**: Minimal
557
+
558
+ #### What Changed
559
+
560
+ With `compatibilityVersion: 5`, Nuxt removes `compilerOptions.baseUrl` from its generated TypeScript configurations. Relative Nuxt and Nitro aliases are resolved from Nuxt's build directory instead of a custom `baseUrl`.
561
+
562
+ #### Reasons for Change
563
+
564
+ TypeScript 6 deprecates `baseUrl`, and it is no longer required when using `paths`. Removing the option also keeps Nuxt's generated aliases anchored consistently to the generated configuration that contains them.
565
+
566
+ #### Migration Steps
567
+
568
+ Remove `baseUrl` from your Nuxt TypeScript configuration. If you used it to anchor a relative Nuxt or Nitro alias, make that alias absolute instead:
569
+
570
+ ```diff [nuxt.config.ts]
571
+ + import { fileURLToPath } from 'node:url'
572
+ +
573
+ export default defineNuxtConfig({
574
+ alias: {
575
+ - images: './assets/images',
576
+ + images: fileURLToPath(new URL('./assets/images', import.meta.url)),
577
+ },
578
+ - typescript: {
579
+ - tsConfig: {
580
+ - compilerOptions: {
581
+ - baseUrl: '..',
582
+ - },
583
+ - },
584
+ - },
585
+ })
586
+ ```
587
+
553
588
  ## Migrating to Nuxt 4
554
589
 
555
590
  Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.
@@ -133,6 +133,58 @@ Static hosts need an HTML shell for client-side routes and missing paths. Nuxt e
133
133
 
134
134
  `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.
135
135
 
136
+ #### Server-rendering the Error Page
137
+
138
+ By default `404.html` is an empty shell, so your `error.vue` (and its layout and data) only appear once the client app has booted. You can prerender it instead:
139
+
140
+ ```ts twoslash [nuxt.config.ts]
141
+ export default defineNuxtConfig({
142
+ experimental: {
143
+ prerenderErrorPages: true,
144
+ },
145
+ })
146
+ ```
147
+
148
+ Nuxt then renders `error.vue` at build time with a synthetic 404 error and writes the result to `404.html`, which hydrates in place at whatever URL your host served it from. Pass an array of status codes between 400 and 599 (`[404, 500]`) to emit additional pages, if your host can serve them.
149
+
150
+ Because a single file is served for every missing path, the error page cannot depend on the request: `useRoute()`, `useRequestURL()` and data fetched with the current path will hold the build-time values in the prerendered HTML and be corrected on hydration. Wrap request-specific markup in [`<ClientOnly>`](/docs/4.x/api/components/client-only), and skip request-specific data fetching with `import.meta.prerender`:
151
+
152
+ ```vue [error.vue]
153
+ <script setup lang="ts">
154
+ import type { NuxtError } from '#app'
155
+
156
+ defineProps<{ error: NuxtError }>()
157
+
158
+ const route = useRoute()
159
+
160
+ const { data: suggestions } = await useAsyncData(
161
+ 'error-suggestions',
162
+ () => $fetch('/api/suggestions', { query: { path: route.path } }),
163
+ // at build time the path is `/404.html`, so fetch on the client instead
164
+ { server: !import.meta.prerender },
165
+ )
166
+ </script>
167
+
168
+ <template>
169
+ <div>
170
+ <h1>{{ error.statusCode }}</h1>
171
+ <ClientOnly>
172
+ <p>Nothing found at {{ route.path }}</p>
173
+ </ClientOnly>
174
+ <ul v-if="suggestions">
175
+ <li
176
+ v-for="suggestion in suggestions"
177
+ :key="suggestion"
178
+ >
179
+ {{ suggestion }}
180
+ </li>
181
+ </ul>
182
+ </div>
183
+ </template>
184
+ ```
185
+
186
+ `import.meta.prerender` is only `true` while the page is being generated, so the same `error.vue` still server-renders its data when the app is deployed with a server.
187
+
136
188
  #### Skipping Client Fallback Generation
137
189
 
138
190
  When prerendering a client-rendered app, Nuxt will generate `index.html`, `200.html` and `404.html` files by default. However, if you need to prevent any (or all) of these files from being generated in your build, you can use the `'prerender:generate'` hook from [Nitro](/docs/4.x/getting-started/prerendering#prerendergenerate-nitro-hook).
@@ -38,6 +38,71 @@ Most applications need multiple pages and a way to navigate between them. This i
38
38
 
39
39
  :link-example{to="/docs/4.x/examples/features/auto-imports"}
40
40
 
41
+ ## Vapor Mode
42
+
43
+ ::warning
44
+ Vapor Mode support is experimental and requires Vue 3.6 or newer. The API may change.
45
+ ::
46
+
47
+ [Vapor Mode](https://github.com/vuejs/core/releases/tag/v3.6.0-rc.1#about-vapor-mode) is an alternative compilation strategy introduced in Vue 3.6 that renders components without the Virtual DOM, lowering memory use and improving runtime performance.
48
+
49
+ Nuxt supports Vapor Mode in **interop mode**: your application is still rendered with the Virtual DOM, and you opt individual components or pages into Vapor by writing them as Vapor single-file components. This lets you adopt Vapor incrementally, and the rest of Nuxt (routing, `useAsyncData`, layouts, and most built-in components) keeps working unchanged.
50
+
51
+ ### Enabling Vapor Mode
52
+
53
+ Enable the `vue.vapor` option in your Nuxt config:
54
+
55
+ ```ts twoslash [nuxt.config.ts]
56
+ export default defineNuxtConfig({
57
+ vue: {
58
+ vapor: true,
59
+ },
60
+ })
61
+ ```
62
+
63
+ This installs Vue's `vaporInteropPlugin`, which lets Vapor and Virtual DOM components render alongside each other. You can then mark any component or page as Vapor by adding the `vapor` attribute to `<script setup>`:
64
+
65
+ ```vue [app/pages/index.vue]
66
+ <script setup vapor lang="ts">
67
+ const count = ref(0)
68
+ </script>
69
+
70
+ <template>
71
+ <button @click="count++">
72
+ count is {{ count }}
73
+ </button>
74
+ </template>
75
+ ```
76
+
77
+ ### Trying it out
78
+
79
+ Vapor Mode needs a version of Vue that includes both Vapor and its interop fixes. While Vue 3.6 is in pre-release, install a release candidate (or newer) that contains those fixes:
80
+
81
+ ```json [package.json]
82
+ {
83
+ "dependencies": {
84
+ "vue": "^3.6.0-rc.2"
85
+ }
86
+ }
87
+ ```
88
+
89
+ If you enable `vue.vapor` on an older version of Vue, Nuxt warns and disables it.
90
+
91
+ We recommend trying Vapor Mode in a fresh project rather than adding it to an existing one. You can also explore a working setup in the [Nuxt Vapor demo](https://github.com/danielroe/nuxt-vapor-demo).
92
+
93
+ ### Known limitations
94
+
95
+ Because Nuxt runs Vapor in interop mode, some patterns that rely on the Virtual DOM behave differently inside Vapor components:
96
+
97
+ - **Full Vapor apps are not yet supported.** The application root stays Virtual DOM and you opt in per component; we may support a full Vapor app later on.
98
+ - **Template refs** on a Vapor component do not expose `$el`.
99
+ - **Some built-in components inspect their slot content** and cannot read Vapor slot children. `<ClientOnly>` skips its attribute-forwarding fallthrough, and `<NuxtIsland>`, server components, and the head components that read text children (such as `<Title>`, `<Style>` and `<Noscript>`) warn if you pass a Vapor slot. Pass the value directly instead (for example, a string to `<Title>`).
100
+ - **The Options API is not supported** in Vapor components, so `asyncData` and `fetchKey` via `defineNuxtComponent` are unavailable. Use `<script setup>` with `useAsyncData` instead.
101
+ - **Keyed `onPrehydrate`** falls back to the unkeyed form (and warns in development), because there is no component instance to attach the key to.
102
+ - **Nuxt composables called after `await`** in a Vapor `<script setup>` may lose the Nuxt context. Call them before the first `await` where possible.
103
+
104
+ Most other Nuxt composables and built-in components work unchanged, because they rely on injection rather than on a component instance.
105
+
41
106
  ## Differences with Nuxt 2 / Vue 2
42
107
 
43
108
  Nuxt 3+ is based on Vue 3. The new major Vue version introduces several changes that Nuxt takes advantage of:
@@ -181,7 +181,7 @@ Server components are experimental, and some rough edges are tracked in open iss
181
181
  - Most features for server-only and island components, such as slots and `nuxt-client` components, are only available for single file components.
182
182
  - Global styles of your application are sent with each island response, and island assets can be loaded twice in some setups ([#29591](https://github.com/nuxt/nuxt/issues/29591)).
183
183
  - Using islands can significantly increase the number of chunks generated at build time ([#34855](https://github.com/nuxt/nuxt/issues/34855)).
184
- - `:slotted()` styles are ignored in server component slots ([#31510](https://github.com/nuxt/nuxt/issues/31510)).
184
+ - With webpack and Rspack, scoped `:slotted()` styles in server component slots can fail because server and client builds may generate different scope IDs ([#31510](https://github.com/nuxt/nuxt/issues/31510)).
185
185
  - Template refs cannot reference elements inside a server component from the parent ([#31512](https://github.com/nuxt/nuxt/issues/31512)).
186
186
  - `inject`/`provide` does not cross the island boundary, so injecting from the page into a standalone server component does not work ([#22751](https://github.com/nuxt/nuxt/issues/22751)).
187
187
  - Server components rendered via the auto-generated wrapper do not expose load and error events; use `<NuxtIsland>` directly if you need its `error` event and `refresh()` method ([#25744](https://github.com/nuxt/nuxt/issues/25744)).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nuxt/docs-nightly",
3
- "version": "4.6.0-29776167.796cdae2",
3
+ "version": "4.6.0-29778602.bfddf2f0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/nuxt/nuxt.git",