@nuxt/docs-nightly 4.6.0-29776185.65fb0aaa → 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.
- package/1.getting-started/06.styling.md +2 -2
- package/1.getting-started/08.seo-meta.md +1 -1
- package/1.getting-started/09.transitions.md +2 -2
- package/1.getting-started/10.data-fetching.md +3 -3
- package/1.getting-started/12.error-handling.md +1 -1
- package/1.getting-started/13.server.md +1 -1
- package/1.getting-started/15.prerendering.md +1 -1
- package/1.getting-started/16.deployment.md +17 -1
- package/1.getting-started/17.testing.md +2 -2
- package/1.getting-started/18.upgrade.md +35 -0
- package/3.guide/1.concepts/1.rendering.md +52 -0
- package/3.guide/1.concepts/10.vuejs-development.md +65 -0
- package/3.guide/1.concepts/6.server-components.md +1 -1
- package/package.json +1 -1
|
@@ -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
|
|
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>`
|
|
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
|
|
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
|
|
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
|
|
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 [
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
|
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
|
|
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)).
|