@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e
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/01.introduction.md +8 -8
- package/1.getting-started/02.installation.md +2 -4
- package/1.getting-started/03.configuration.md +16 -16
- package/1.getting-started/04.views.md +8 -8
- package/1.getting-started/05.assets.md +10 -10
- package/1.getting-started/06.styling.md +10 -10
- package/1.getting-started/07.routing.md +15 -15
- package/1.getting-started/08.seo-meta.md +15 -15
- package/1.getting-started/09.transitions.md +10 -10
- package/1.getting-started/10.data-fetching.md +61 -47
- package/1.getting-started/11.state-management.md +11 -11
- package/1.getting-started/12.error-handling.md +20 -18
- package/1.getting-started/13.server.md +7 -7
- package/1.getting-started/14.layers.md +6 -6
- package/1.getting-started/15.prerendering.md +22 -28
- package/1.getting-started/16.deployment.md +22 -6
- package/1.getting-started/17.testing.md +200 -21
- package/1.getting-started/18.upgrade.md +78 -278
- package/2.directory-structure/0.nuxt.md +2 -2
- package/2.directory-structure/0.output.md +3 -3
- package/2.directory-structure/1.app/1.assets.md +3 -3
- package/2.directory-structure/1.app/1.components.md +26 -109
- package/2.directory-structure/1.app/1.composables.md +5 -5
- package/2.directory-structure/1.app/1.layouts.md +10 -10
- package/2.directory-structure/1.app/1.middleware.md +14 -10
- package/2.directory-structure/1.app/1.pages.md +25 -20
- package/2.directory-structure/1.app/1.plugins.md +7 -7
- package/2.directory-structure/1.app/1.utils.md +9 -5
- package/2.directory-structure/1.app/3.app-config.md +7 -7
- package/2.directory-structure/1.app/3.app.md +6 -6
- package/2.directory-structure/1.app/3.error.md +1 -1
- package/2.directory-structure/1.content.md +1 -1
- package/2.directory-structure/1.layers.md +13 -13
- package/2.directory-structure/1.modules.md +3 -3
- package/2.directory-structure/1.node_modules.md +1 -1
- package/2.directory-structure/1.server.md +33 -14
- package/2.directory-structure/1.shared.md +7 -5
- package/2.directory-structure/1.test.md +25 -0
- package/2.directory-structure/2.env.md +7 -7
- package/2.directory-structure/2.nuxtignore.md +3 -3
- package/2.directory-structure/2.nuxtrc.md +3 -3
- package/2.directory-structure/3.nuxt-config.md +2 -2
- package/2.directory-structure/3.tsconfig.md +21 -11
- package/2.directory-structure/index.md +29 -25
- package/3.guide/0.index.md +6 -6
- package/3.guide/1.concepts/1.rendering.md +76 -12
- package/3.guide/1.concepts/10.vuejs-development.md +73 -8
- package/3.guide/1.concepts/2.nuxt-lifecycle.md +18 -18
- package/3.guide/1.concepts/3.auto-imports.md +11 -11
- package/3.guide/1.concepts/4.server-engine.md +6 -6
- package/3.guide/1.concepts/5.modules.md +4 -4
- package/3.guide/1.concepts/6.server-components.md +198 -0
- package/3.guide/1.concepts/7.esm.md +5 -5
- package/3.guide/1.concepts/8.typescript.md +9 -9
- package/3.guide/2.best-practices/accessibility.md +155 -0
- package/3.guide/2.best-practices/hydration.md +5 -5
- package/3.guide/2.best-practices/performance.md +13 -9
- package/3.guide/3.ai/1.mcp.md +104 -19
- package/3.guide/4.modules/2.module-anatomy.md +5 -5
- package/3.guide/4.modules/3.recipes-basics.md +8 -8
- package/3.guide/4.modules/4.module-dependencies.md +1 -1
- package/3.guide/4.modules/5.recipes-advanced.md +6 -8
- package/3.guide/4.modules/6.testing.md +2 -2
- package/3.guide/4.modules/7.best-practices.md +2 -2
- package/3.guide/4.modules/9.server-compatibility.md +215 -0
- package/3.guide/4.modules/index.md +9 -9
- package/3.guide/5.recipes/1.custom-routing.md +15 -11
- package/3.guide/5.recipes/2.vite-plugin.md +3 -3
- package/3.guide/5.recipes/3.custom-usefetch.md +5 -5
- package/3.guide/5.recipes/4.sessions-and-authentication.md +2 -2
- package/3.guide/5.recipes/5.mostly-static-sites.md +127 -0
- package/3.guide/6.going-further/1.events.md +1 -1
- package/3.guide/6.going-further/1.experimental-features.md +254 -22
- package/3.guide/6.going-further/1.features.md +42 -6
- package/3.guide/6.going-further/1.internals.md +10 -10
- package/3.guide/6.going-further/10.runtime-config.md +28 -6
- package/3.guide/6.going-further/11.nightly-release-channel.md +1 -1
- package/3.guide/6.going-further/2.hooks.md +6 -6
- package/3.guide/6.going-further/4.kit.md +4 -4
- package/3.guide/6.going-further/5.server-imports.md +221 -0
- package/3.guide/6.going-further/6.nuxt-app.md +7 -7
- package/3.guide/6.going-further/7.layers.md +13 -13
- package/3.guide/6.going-further/8.builders.md +38 -14
- package/4.api/1.components/1.nuxt-client-fallback.md +1 -1
- package/4.api/1.components/10.nuxt-picture.md +1 -1
- package/4.api/1.components/11.teleports.md +1 -1
- package/4.api/1.components/12.nuxt-route-announcer.md +5 -3
- package/4.api/1.components/14.nuxt-announcer.md +3 -3
- package/4.api/1.components/2.nuxt-page.md +5 -5
- package/4.api/1.components/3.nuxt-layout.md +8 -8
- package/4.api/1.components/4.nuxt-link.md +6 -4
- package/4.api/1.components/5.nuxt-loading-indicator.md +3 -3
- package/4.api/1.components/6.nuxt-error-boundary.md +1 -1
- package/4.api/1.components/8.nuxt-island.md +5 -5
- package/4.api/2.composables/create-use-async-data.md +51 -8
- package/4.api/2.composables/create-use-fetch.md +126 -9
- package/4.api/2.composables/use-announcer.md +3 -3
- package/4.api/2.composables/use-app-config.md +1 -1
- package/4.api/2.composables/use-async-data.md +19 -11
- package/4.api/2.composables/use-cookie.md +22 -6
- package/4.api/2.composables/use-error.md +1 -1
- package/4.api/2.composables/use-fetch.md +14 -10
- package/4.api/2.composables/use-head-safe.md +2 -2
- package/4.api/2.composables/use-head.md +2 -2
- package/4.api/2.composables/use-hydration.md +1 -1
- package/4.api/2.composables/use-layout.md +1 -1
- package/4.api/2.composables/use-lazy-async-data.md +8 -8
- package/4.api/2.composables/use-lazy-fetch.md +11 -11
- package/4.api/2.composables/use-loading-indicator.md +2 -2
- package/4.api/2.composables/use-nuxt-app.md +13 -13
- package/4.api/2.composables/use-nuxt-data.md +1 -1
- package/4.api/2.composables/use-preview-mode.md +3 -3
- package/4.api/2.composables/use-request-event.md +29 -3
- package/4.api/2.composables/use-request-fetch.md +2 -2
- package/4.api/2.composables/use-request-header.md +1 -1
- package/4.api/2.composables/use-request-headers.md +1 -1
- package/4.api/2.composables/use-request-url.md +1 -1
- package/4.api/2.composables/use-response-header.md +2 -2
- package/4.api/2.composables/use-route-announcer.md +4 -2
- package/4.api/2.composables/use-route.md +2 -2
- package/4.api/2.composables/use-router.md +5 -5
- package/4.api/2.composables/use-runtime-config.md +5 -5
- package/4.api/2.composables/use-runtime-hook.md +1 -1
- package/4.api/2.composables/use-seo-meta.md +3 -3
- package/4.api/2.composables/use-server-seo-meta.md +5 -5
- package/4.api/2.composables/use-state.md +4 -4
- package/4.api/3.utils/$fetch.md +5 -5
- package/4.api/3.utils/abort-navigation.md +1 -1
- package/4.api/3.utils/add-route-middleware.md +2 -2
- package/4.api/3.utils/call-once.md +3 -3
- package/4.api/3.utils/clear-error.md +2 -2
- package/4.api/3.utils/clear-nuxt-data.md +1 -1
- package/4.api/3.utils/clear-nuxt-state.md +2 -2
- package/4.api/3.utils/create-error.md +19 -1
- package/4.api/3.utils/define-nuxt-plugin.md +2 -2
- package/4.api/3.utils/define-nuxt-route-middleware.md +3 -3
- package/4.api/3.utils/define-page-meta.md +12 -12
- package/4.api/3.utils/define-route-rules.md +4 -4
- package/4.api/3.utils/define-use-async-data-addon.md +57 -0
- package/4.api/3.utils/define-use-fetch-addon.md +168 -0
- package/4.api/3.utils/navigate-to.md +6 -2
- package/4.api/3.utils/prefetch-components.md +1 -1
- package/4.api/3.utils/preload-route-components.md +2 -2
- package/4.api/3.utils/prerender-routes.md +3 -3
- package/4.api/3.utils/refresh-cookie.md +1 -1
- package/4.api/3.utils/refresh-nuxt-data.md +3 -3
- package/4.api/3.utils/reload-nuxt-app.md +1 -1
- package/4.api/3.utils/set-page-layout.md +1 -1
- package/4.api/3.utils/set-response-status.md +2 -2
- package/4.api/3.utils/show-error.md +3 -3
- package/4.api/3.utils/update-app-config.md +2 -2
- package/4.api/4.commands/README.md +9 -0
- package/4.api/5.kit/1.modules.md +3 -3
- package/4.api/5.kit/10.runtime-config.md +1 -1
- package/4.api/5.kit/10.templates.md +42 -0
- package/4.api/5.kit/12.nitro.md +59 -18
- package/4.api/5.kit/14.logging.md +56 -2
- package/4.api/5.kit/15.builder.md +1 -1
- package/4.api/5.kit/18.dependencies.md +90 -0
- package/4.api/5.kit/2.programmatic.md +78 -1
- package/4.api/5.kit/3.compatibility.md +2 -2
- package/4.api/5.kit/4.autoimports.md +13 -13
- package/4.api/5.kit/5.components.md +3 -3
- package/4.api/5.kit/6.context.md +2 -2
- package/4.api/5.kit/7.pages.md +35 -4
- package/4.api/5.kit/8.layout.md +1 -1
- package/4.api/6.advanced/1.hooks.md +6 -3
- package/4.api/6.nuxt-config.md +44 -21
- package/4.api/index.md +7 -7
- package/5.community/2.getting-help.md +1 -1
- package/5.community/3.reporting-bugs.md +1 -1
- package/5.community/4.contribution.md +14 -12
- package/5.community/5.framework-contribution.md +4 -4
- package/5.community/6.roadmap.md +6 -6
- package/6.bridge/1.overview.md +12 -12
- package/6.bridge/2.typescript.md +1 -1
- package/6.bridge/3.bridge-composition-api.md +6 -6
- package/6.bridge/4.plugins-and-middleware.md +4 -4
- package/6.bridge/5.nuxt3-compatible-api.md +9 -9
- package/6.bridge/6.meta.md +5 -5
- package/6.bridge/7.runtime-config.md +1 -1
- package/6.bridge/8.nitro.md +1 -1
- package/6.bridge/9.vite.md +1 -1
- package/7.migration/1.overview.md +2 -2
- package/7.migration/10.bundling.md +1 -1
- package/7.migration/11.server.md +3 -3
- package/7.migration/2.configuration.md +6 -6
- package/7.migration/20.module-authors.md +7 -7
- package/7.migration/3.auto-imports.md +3 -3
- package/7.migration/4.meta.md +4 -4
- package/7.migration/5.plugins-and-middleware.md +3 -3
- package/7.migration/6.pages-and-layouts.md +13 -13
- package/7.migration/7.component-options.md +15 -15
- package/7.migration/8.runtime-config.md +4 -4
- package/README.md +1 -1
- package/errors/e8007.md +28 -0
- package/package.json +2 -2
- package/4.api/4.commands/.navigation.yml +0 -3
- package/4.api/4.commands/add.md +0 -112
- package/4.api/4.commands/analyze.md +0 -42
- package/4.api/4.commands/build-module.md +0 -42
- package/4.api/4.commands/build.md +0 -48
- package/4.api/4.commands/cleanup.md +0 -38
- package/4.api/4.commands/dev.md +0 -61
- package/4.api/4.commands/devtools.md +0 -38
- package/4.api/4.commands/generate.md +0 -43
- package/4.api/4.commands/info.md +0 -33
- package/4.api/4.commands/init.md +0 -50
- package/4.api/4.commands/module.md +0 -84
- package/4.api/4.commands/prepare.md +0 -41
- package/4.api/4.commands/preview.md +0 -44
- package/4.api/4.commands/test.md +0 -40
- package/4.api/4.commands/typecheck.md +0 -44
- package/4.api/4.commands/upgrade.md +0 -37
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Server Compatibility"
|
|
3
|
+
description: "Ship one module that serves Nuxt 4 and Nuxt 5, whichever server runtime is underneath."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Nuxt supports multiple server runtimes. Nuxt 3 and 4 target Nitro v2 (`nitropack`), which uses `h3` v1; Nuxt 5 defaults to Nitro v3 (`nitro`), which uses `h3` v2. It is also possible to use a custom server runtime based on Web APIs, which is compatible everywhere (`nuxt/server`).
|
|
7
|
+
|
|
8
|
+
This guide covers how to write a module whose server code runs on all of them.
|
|
9
|
+
|
|
10
|
+
::note
|
|
11
|
+
If your module has no server code, nothing here applies.
|
|
12
|
+
::
|
|
13
|
+
|
|
14
|
+
## Recommended Migration
|
|
15
|
+
|
|
16
|
+
[`nuxt/server`](/docs/guide/going-further/server-imports) is the import surface for writing agnostic server code based on Web APIs, and it ships in Nuxt 4.6+. Code written with it runs on `nitropack` v2, on Nitro v3, and under other server builders, such as `@nuxt/vite-server`.
|
|
17
|
+
|
|
18
|
+
### Event Handlers
|
|
19
|
+
|
|
20
|
+
If you are registering event handlers, keep your current handler (for compatibility with Nuxt <4.6) and add a new portable one using `nuxt/server` beside it, and register both. Nuxt will register the implementation the application can run: the portable file under Nitro v3 and under other builders, the v2 file on a host still running `nitropack` v2.
|
|
21
|
+
|
|
22
|
+
```ts [module.ts]
|
|
23
|
+
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
|
|
24
|
+
|
|
25
|
+
export default defineNuxtModule({
|
|
26
|
+
meta: { name: 'my-module' },
|
|
27
|
+
setup () {
|
|
28
|
+
const { resolve } = createResolver(import.meta.url)
|
|
29
|
+
|
|
30
|
+
addServerHandler({
|
|
31
|
+
route: '/api/my-module/status',
|
|
32
|
+
handler: {
|
|
33
|
+
nuxt: resolve('./runtime/server/status'),
|
|
34
|
+
nitro2: resolve('./runtime/server/status.legacy'),
|
|
35
|
+
},
|
|
36
|
+
})
|
|
37
|
+
},
|
|
38
|
+
})
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The two files differ in their imports, and wherever the handler uses an h3 v1 helper or behavior that `nuxt/server` handles differently:
|
|
42
|
+
|
|
43
|
+
::code-group
|
|
44
|
+
|
|
45
|
+
```ts [runtime/server/status.ts]
|
|
46
|
+
import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'
|
|
47
|
+
|
|
48
|
+
export default defineEventHandler(() => ({
|
|
49
|
+
version: useRuntimeConfig().public.myModule.version,
|
|
50
|
+
}))
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```ts [runtime/server/status.legacy.ts]
|
|
54
|
+
// @ts-expect-error `#imports` is typed for the app, not the server build
|
|
55
|
+
import { useRuntimeConfig } from '#imports'
|
|
56
|
+
import { defineEventHandler } from 'h3'
|
|
57
|
+
|
|
58
|
+
export default defineEventHandler(event => ({
|
|
59
|
+
version: useRuntimeConfig(event).public.myModule.version,
|
|
60
|
+
}))
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
::
|
|
64
|
+
|
|
65
|
+
::read-more{to="/docs/getting-started/upgrade#differences-from-h3-v1"}
|
|
66
|
+
See every difference between h3 v1 and `nuxt/server`, and what to use instead.
|
|
67
|
+
::
|
|
68
|
+
|
|
69
|
+
The keys indicate which server API each file relies upon:
|
|
70
|
+
|
|
71
|
+
| Key | The file imports | Where it runs |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| `nuxt` | `nuxt/server` only | Any server builder, from Nuxt 4.6 |
|
|
74
|
+
| `nitro2` | `h3`, `nitropack/runtime`, `#imports` | `nitropack` v2 |
|
|
75
|
+
| `nitro3` | `nitro`, `nitro/h3`, alone or alongside `nuxt/server` | The Nitro server builder, v3 |
|
|
76
|
+
|
|
77
|
+
Nuxt will pick the most appropriate handler to use based on the server builder a user is using. If you register a handler which the user's server builder cannot run, it will be skipped with a warning.
|
|
78
|
+
|
|
79
|
+
::tip
|
|
80
|
+
Use `nitro3` only for code that needs an API only Nitro v3 offers. Using `nuxt/server` will keep your code more portable in future.
|
|
81
|
+
::
|
|
82
|
+
|
|
83
|
+
Using this pattern means you will support both old (<4.6) and new versions of Nuxt (including Nuxt 5).
|
|
84
|
+
|
|
85
|
+
::important
|
|
86
|
+
The object form of `handler` needs `@nuxt/kit@^4.6` in your module's `dependencies`, which is what the [module starter](/docs/guide/modules/getting-started) sets up. If `@nuxt/kit` is only a `devDependency` and left external when you build, or is a `peerDependency`, the application's version runs instead, and a version older than 4.6 fails on the object `handler`.
|
|
87
|
+
::
|
|
88
|
+
|
|
89
|
+
To typecheck the `nuxt` files, install `nuxt@>=4.6` as a `devDependency`. To typecheck `nitro3` files, also install `nitro`.
|
|
90
|
+
|
|
91
|
+
If your module's own aliases already resolve to the right code on both Nitro majors, register the same file for both keys (`{ nitro2: file, nitro3: file }`) or set [`meta.compatibility.server`](#declaring-what-you-cannot-infer).
|
|
92
|
+
|
|
93
|
+
On a `nitropack` v2 host, Nuxt prefers the `nitro2` variant, so the `nuxt` variant only runs there if it is the only one registered. Test the `nuxt` variant on Nuxt 5.
|
|
94
|
+
|
|
95
|
+
In playgrounds and test fixtures on Nuxt 5, h3's auto-imported `defineEventHandler` is not available: import it from `nuxt/server`.
|
|
96
|
+
|
|
97
|
+
### Server Utilities
|
|
98
|
+
|
|
99
|
+
If your module exposes utilities that take the event (through an alias, `addServerImports` or a type template), type the parameter as `RequestEvent` from `nuxt/server`, or as the part it reads, such as `Pick<RequestEvent, 'req' | 'context'>`. A parameter typed as `H3Event` only accepts the event of one h3 major, so the utility can't be called from a `nuxt/server` handler.
|
|
100
|
+
|
|
101
|
+
`getNitroVersion` reports the Nitro major, not which server API the host runs: a host with a different `server.builder` runs none of the Nitro ones.
|
|
102
|
+
|
|
103
|
+
### Server Plugins
|
|
104
|
+
|
|
105
|
+
Server plugins take variants too, although they are specific to Nitro so there is no generic `nuxt` variant to register.
|
|
106
|
+
|
|
107
|
+
::tip
|
|
108
|
+
Because `defineNitroPlugin` is an identity function, you may be able to replace it with a type annotation to write code that's portable for both `nitro2` and `nitro3`.
|
|
109
|
+
::
|
|
110
|
+
|
|
111
|
+
```ts [module.ts]
|
|
112
|
+
import { addNitroPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
|
|
113
|
+
|
|
114
|
+
export default defineNuxtModule({
|
|
115
|
+
meta: { name: 'my-module' },
|
|
116
|
+
setup () {
|
|
117
|
+
const { resolve } = createResolver(import.meta.url)
|
|
118
|
+
|
|
119
|
+
addNitroPlugin({
|
|
120
|
+
nitro2: resolve('./runtime/server/plugin.legacy'),
|
|
121
|
+
nitro3: resolve('./runtime/server/plugin'),
|
|
122
|
+
})
|
|
123
|
+
},
|
|
124
|
+
})
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Other Variants
|
|
128
|
+
|
|
129
|
+
For anything else that points at server code, such as an alias, a type template or an app plugin that reads the server event, you can use `resolveServerVariant` to resolve the variant that is appropriate for this version of Nuxt, or `undefined` if it runs none of them.
|
|
130
|
+
|
|
131
|
+
`addServerImports` accepts the same variants in `from`.
|
|
132
|
+
|
|
133
|
+
```ts [module.ts]
|
|
134
|
+
import { addServerImports, createResolver, defineNuxtModule, resolveServerVariant } from '@nuxt/kit'
|
|
135
|
+
|
|
136
|
+
export default defineNuxtModule({
|
|
137
|
+
meta: { name: 'my-module' },
|
|
138
|
+
setup (_options, nuxt) {
|
|
139
|
+
const { resolve } = createResolver(import.meta.url)
|
|
140
|
+
|
|
141
|
+
const someServerFile = resolveServerVariant({
|
|
142
|
+
nuxt: resolve('./runtime/server'),
|
|
143
|
+
nitro2: resolve('./runtime/server.legacy'),
|
|
144
|
+
})
|
|
145
|
+
|
|
146
|
+
if (someServerFile) {
|
|
147
|
+
nuxt.options.alias['#my-module/server'] = someServerFile
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
addServerImports({
|
|
151
|
+
name: 'verifyToken',
|
|
152
|
+
from: { nuxt: resolve('./runtime/verify'), nitro2: resolve('./runtime/verify.legacy') },
|
|
153
|
+
})
|
|
154
|
+
},
|
|
155
|
+
})
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
If running with `nitropack` v2, `nitro2` will always be preferred over `nuxt`, and if running with `nitro` v3, `nitro3` will always be preferred over `nuxt`. So, if you need to test the `nuxt` variant, set `server.builder` in your test fixture to a builder that is not Nitro, such as `@nuxt/vite-server`.
|
|
159
|
+
|
|
160
|
+
### Declaring What You Cannot Infer
|
|
161
|
+
|
|
162
|
+
Nuxt reads a registered file's imports to decide which API it uses, so you don't need to declare your compatibility. But if this isn't sufficient, you can set `meta.compatibility.server`:
|
|
163
|
+
|
|
164
|
+
```ts [module.ts]
|
|
165
|
+
export default defineNuxtModule({
|
|
166
|
+
meta: {
|
|
167
|
+
name: 'my-module',
|
|
168
|
+
compatibility: { server: 'nuxt' },
|
|
169
|
+
},
|
|
170
|
+
})
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
If we can't tell, code will be treated as `nitro2`.
|
|
174
|
+
|
|
175
|
+
### Typing Runtime Config and Events
|
|
176
|
+
|
|
177
|
+
To type runtime config keys your module adds, augment `RuntimeConfig` (or `PublicRuntimeConfig`) from `nuxt/schema`. The keys are then typed in `nuxt`, `nitro2` and `nitro3` files alike.
|
|
178
|
+
|
|
179
|
+
```ts [module.ts]
|
|
180
|
+
declare module 'nuxt/schema' {
|
|
181
|
+
interface RuntimeConfig {
|
|
182
|
+
myModule: { apiKey: string }
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Builder-specific types, such as `H3Event` for `useRequestEvent()` or the full Nitro config in the `nitro:config` hook, come from the generated `.nuxt/nuxt.d.ts`. Without it, they resolve to builder-agnostic types (`RequestEvent` and a reduced Nitro config). Type utilities that accept an event against `RequestEvent` to support any server builder.
|
|
188
|
+
|
|
189
|
+
### Plugins, Storage and Caching
|
|
190
|
+
|
|
191
|
+
A module built on server plugins, storage or caching has no `nuxt` variant, because `nuxt/server` doesn't cover those areas. Register its files as `nitro2` now, and add a `nitro3` variant when you port them.
|
|
192
|
+
|
|
193
|
+
## Nitro-specific Code
|
|
194
|
+
|
|
195
|
+
`nuxt/server` covers request and response work: handlers, errors, router params, query and body reading and validation, headers, CORS, cookies, sessions, redirects, route rules, runtime config, app config, in-process fetch with `serverFetch()` and runtime hooks with `useServerHooks()`. But Nitro covers a lot more, so if you need any of these areas, you might need to stay on Nitro's own imports inside a `nitro2` or `nitro3` file.
|
|
196
|
+
|
|
197
|
+
Use the specifiers of the version the file is for. A file that imports `nitro/*` is read as Nitro 3 code, so a `nitro2` file must import `h3` and `nitropack/*` instead:
|
|
198
|
+
|
|
199
|
+
| Area | In a `nitro2` file | In a `nitro3` file |
|
|
200
|
+
| --- | --- | --- |
|
|
201
|
+
| Storage: `useStorage()` and its driver configuration | `nitropack/runtime` | `nitro/storage` |
|
|
202
|
+
| Caching: `defineCachedEventHandler()`, `defineCachedFunction()` | `nitropack/runtime` | `nitro/cache` |
|
|
203
|
+
| Server plugins | `defineNitroPlugin()` from `nitropack/runtime` | `definePlugin()` from `nitro` |
|
|
204
|
+
| Nitro's own runtime hooks, such as `request` and `error` | `useNitroApp().hooks` from `nitropack/runtime` | `useNitroHooks()` from `nitro/app` |
|
|
205
|
+
| Lazy handlers: `lazyEventHandler()` | `h3` | `nitro/h3` |
|
|
206
|
+
|
|
207
|
+
Tasks are also not supported by `nuxt/server`.
|
|
208
|
+
|
|
209
|
+
::read-more{to="/docs/guide/going-further/server-imports#reaching-past-the-surface"}
|
|
210
|
+
See which h3 helpers work with the portable event, and which need Nitro-specific utilities.
|
|
211
|
+
::
|
|
212
|
+
|
|
213
|
+
## Notable Changes in Nitro v3
|
|
214
|
+
|
|
215
|
+
If a `nitro2` file is all you ship, it will keep running on Nuxt 5 through the Nitro v2 compatibility layer, which is documented in the [Nuxt 5 module server compatibility guide](https://nuxt.com/docs/5.x/guide/modules/server-compatibility) along with the behaviours that changed with Nitro v3.
|
|
@@ -6,34 +6,34 @@ navigation: false
|
|
|
6
6
|
surround: false
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
Nuxt's [configuration](/docs/
|
|
9
|
+
Nuxt's [configuration](/docs/api/nuxt-config) and [hooks](/docs/guide/going-further/hooks) systems make it possible to customize every aspect of Nuxt and add any integration you might need (Vue plugins, CMS, server routes, components, logging, etc.).
|
|
10
10
|
|
|
11
11
|
**Nuxt modules** are functions that sequentially run when starting Nuxt in development mode using `nuxt dev` or building a project for production with `nuxt build`.
|
|
12
12
|
With modules, you can encapsulate, properly test, and share custom solutions as npm packages without adding unnecessary boilerplate to your project, or requiring changes to Nuxt itself.
|
|
13
13
|
|
|
14
14
|
::card-group{class="sm:grid-cols-1"}
|
|
15
|
-
::card{icon="i-lucide-rocket" title="Create Your First Module" to="/docs/
|
|
15
|
+
::card{icon="i-lucide-rocket" title="Create Your First Module" to="/docs/guide/modules/getting-started"}
|
|
16
16
|
Learn how to create your first Nuxt module using the official starter template.
|
|
17
17
|
::
|
|
18
|
-
::card{icon="i-lucide-box" title="Understand Module Structure" to="/docs/
|
|
18
|
+
::card{icon="i-lucide-box" title="Understand Module Structure" to="/docs/guide/modules/module-anatomy"}
|
|
19
19
|
Learn how Nuxt modules are structured and how to define them.
|
|
20
20
|
::
|
|
21
|
-
::card{icon="i-lucide-code" title="Add Plugins, Components & More" to="/docs/
|
|
21
|
+
::card{icon="i-lucide-code" title="Add Plugins, Components & More" to="/docs/guide/modules/recipes-basics"}
|
|
22
22
|
Learn how to inject plugins, components, composables and server routes from your module.
|
|
23
23
|
::
|
|
24
|
-
::card{icon="i-lucide-link" title="Depend on Other Modules" to="/docs/
|
|
24
|
+
::card{icon="i-lucide-link" title="Depend on Other Modules" to="/docs/guide/modules/module-dependencies"}
|
|
25
25
|
Declare dependencies on other modules with version constraints and configuration merging.
|
|
26
26
|
::
|
|
27
|
-
::card{icon="i-lucide-layers" title="Use Hooks & Extend Types" to="/docs/
|
|
27
|
+
::card{icon="i-lucide-layers" title="Use Hooks & Extend Types" to="/docs/guide/modules/recipes-advanced"}
|
|
28
28
|
Master lifecycle hooks, virtual files and TypeScript declarations in your modules.
|
|
29
29
|
::
|
|
30
|
-
::card{icon="i-lucide-test-tube" title="Test Your Module" to="/docs/
|
|
30
|
+
::card{icon="i-lucide-test-tube" title="Test Your Module" to="/docs/guide/modules/testing"}
|
|
31
31
|
Learn how to test your Nuxt module with unit, integration and E2E tests.
|
|
32
32
|
::
|
|
33
|
-
::card{icon="i-lucide-medal" title="Follow Best Practices" to="/docs/
|
|
33
|
+
::card{icon="i-lucide-medal" title="Follow Best Practices" to="/docs/guide/modules/best-practices"}
|
|
34
34
|
Build performant and maintainable Nuxt modules with these guidelines.
|
|
35
35
|
::
|
|
36
|
-
::card{icon="i-lucide-globe" title="Publish & Share Your Module" to="/docs/
|
|
36
|
+
::card{icon="i-lucide-globe" title="Publish & Share Your Module" to="/docs/guide/modules/ecosystem"}
|
|
37
37
|
Join the Nuxt module ecosystem and publish your module to npm.
|
|
38
38
|
::
|
|
39
39
|
::
|
|
@@ -5,11 +5,11 @@ description: "In Nuxt, your routing is defined by the structure of your files in
|
|
|
5
5
|
|
|
6
6
|
## Adding Custom Routes
|
|
7
7
|
|
|
8
|
-
In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/
|
|
8
|
+
In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/directory-structure/app/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.
|
|
9
9
|
|
|
10
10
|
### Router Config
|
|
11
11
|
|
|
12
|
-
Using [router options](/docs/
|
|
12
|
+
Using [router options](/docs/guide/recipes/custom-routing#router-options), you can optionally override or extend your routes using a function that accepts the scanned routes and returns customized routes.
|
|
13
13
|
|
|
14
14
|
If it returns `null` or `undefined`, Nuxt will fall back to the default routes (useful to modify input array).
|
|
15
15
|
|
|
@@ -29,7 +29,7 @@ export default {
|
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
::note
|
|
32
|
-
Nuxt will not augment any new routes you return from the `routes` function with metadata defined in `definePageMeta` of the component you provide. If you want that to happen, you should use the `pages:extend` hook which is [called at build-time](/docs/
|
|
32
|
+
Nuxt will not augment any new routes you return from the `routes` function with metadata defined in `definePageMeta` of the component you provide. If you want that to happen, you should use the `pages:extend` hook which is [called at build-time](/docs/api/advanced/hooks#nuxt-hooks-build-time).
|
|
33
33
|
::
|
|
34
34
|
|
|
35
35
|
### Pages Hook
|
|
@@ -75,17 +75,17 @@ export default defineNuxtConfig({
|
|
|
75
75
|
|
|
76
76
|
If you plan to add a whole set of pages related with a specific functionality, you might want to use a [Nuxt module](/modules).
|
|
77
77
|
|
|
78
|
-
The [Nuxt kit](/docs/
|
|
79
|
-
- [`extendPages`](/docs/
|
|
80
|
-
- [`extendRouteRules`](/docs/
|
|
78
|
+
The [Nuxt kit](/docs/guide/going-further/kit) provides a few ways [to add routes](/docs/api/kit/pages):
|
|
79
|
+
- [`extendPages`](/docs/api/kit/pages#extendpages) (callback: pages => void)
|
|
80
|
+
- [`extendRouteRules`](/docs/api/kit/pages#extendrouterules) (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)
|
|
81
81
|
|
|
82
82
|
## Router Options
|
|
83
83
|
|
|
84
|
-
On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions), Nuxt offers [additional options](/docs/
|
|
84
|
+
On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions), Nuxt offers [additional options](/docs/api/nuxt-config#router) to customize the router.
|
|
85
85
|
|
|
86
86
|
### Using `router.options`
|
|
87
87
|
|
|
88
|
-
This is the recommended way to specify [router options](/docs/
|
|
88
|
+
This is the recommended way to specify [router options](/docs/api/nuxt-config#router).
|
|
89
89
|
|
|
90
90
|
```ts [app/router.options.ts]
|
|
91
91
|
import type { RouterConfig } from '@nuxt/schema'
|
|
@@ -119,7 +119,7 @@ export default defineNuxtConfig({
|
|
|
119
119
|
|
|
120
120
|
### Using `nuxt.config`
|
|
121
121
|
|
|
122
|
-
**Note:** Only JSON serializable [options](/docs/
|
|
122
|
+
**Note:** Only JSON serializable [options](/docs/api/nuxt-config#router) are configurable:
|
|
123
123
|
|
|
124
124
|
- `linkActiveClass`
|
|
125
125
|
- `linkExactActiveClass`
|
|
@@ -137,9 +137,13 @@ export default defineNuxtConfig({
|
|
|
137
137
|
})
|
|
138
138
|
```
|
|
139
139
|
|
|
140
|
+
::note
|
|
141
|
+
With `future.compatibilityVersion: 5`, routing is case-sensitive by default to match Nitro. Set `router.options.sensitive` to `false` to opt out.
|
|
142
|
+
::
|
|
143
|
+
|
|
140
144
|
### Hash Mode (SPA)
|
|
141
145
|
|
|
142
|
-
You can enable hash history in SPA mode using the `hashMode` [config](/docs/
|
|
146
|
+
You can enable hash history in SPA mode using the `hashMode` [config](/docs/api/nuxt-config#router). In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the **URL is never sent to the server** and **SSR is not supported**.
|
|
143
147
|
|
|
144
148
|
```ts [nuxt.config.ts]
|
|
145
149
|
export default defineNuxtConfig({
|
|
@@ -154,7 +158,7 @@ export default defineNuxtConfig({
|
|
|
154
158
|
|
|
155
159
|
### Scroll Behavior for hash links
|
|
156
160
|
|
|
157
|
-
You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/
|
|
161
|
+
You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/api/nuxt-config#router) to be `smooth` and you load a page with a hash link (e.g. `https://example.com/blog/my-article#comments`), you will see that the browser smoothly scrolls to this anchor.
|
|
158
162
|
|
|
159
163
|
```ts [nuxt.config.ts]
|
|
160
164
|
export default defineNuxtConfig({
|
|
@@ -32,7 +32,7 @@ First, we need to install the Vite plugin, for our example, we'll use `@rollup/p
|
|
|
32
32
|
|
|
33
33
|
::
|
|
34
34
|
|
|
35
|
-
Next, we need to import and add it to our [`nuxt.config.ts`](/docs/
|
|
35
|
+
Next, we need to import and add it to our [`nuxt.config.ts`](/docs/directory-structure/nuxt-config) file:
|
|
36
36
|
|
|
37
37
|
```ts [nuxt.config.ts]
|
|
38
38
|
import yaml from '@rollup/plugin-yaml'
|
|
@@ -70,7 +70,7 @@ import config from '~/data/hello.yaml'
|
|
|
70
70
|
|
|
71
71
|
## Using Vite Plugins in Nuxt Modules
|
|
72
72
|
|
|
73
|
-
If you're developing a Nuxt module and need to add Vite plugins, you should use the [`addVitePlugin`](/docs/
|
|
73
|
+
If you're developing a Nuxt module and need to add Vite plugins, you should use the [`addVitePlugin`](/docs/api/kit/builder#addviteplugin) utility:
|
|
74
74
|
|
|
75
75
|
```ts [modules/my-module.ts]
|
|
76
76
|
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
|
|
@@ -105,6 +105,6 @@ export default defineNuxtModule({
|
|
|
105
105
|
If you're writing code that needs to access resolved Vite configuration, you should use the `config` and `configResolved` hooks _within_ your Vite plugin, rather than using Nuxt's `vite:extend`, `vite:extendConfig` and `vite:configResolved`.
|
|
106
106
|
::
|
|
107
107
|
|
|
108
|
-
::read-more{to="/docs/
|
|
108
|
+
::read-more{to="/docs/api/kit/builder#addviteplugin"}
|
|
109
109
|
Read more about `addVitePlugin` in the Nuxt Kit documentation.
|
|
110
110
|
::
|
|
@@ -6,7 +6,7 @@ description: How to create a custom fetcher for calling your external API in Nux
|
|
|
6
6
|
|
|
7
7
|
When working with Nuxt, you might be making the frontend and fetching an external API, and you might want to set some default options for fetching from your API.
|
|
8
8
|
|
|
9
|
-
The [`$fetch`](/docs/
|
|
9
|
+
The [`$fetch`](/docs/api/utils/dollarfetch) utility function (used by the [`useFetch`](/docs/api/composables/use-fetch) composable) is intentionally not globally configurable. This is important so that fetching behavior throughout your application remains consistent, and other integrations (like modules) can rely on the behavior of core utilities like `$fetch`.
|
|
10
10
|
|
|
11
11
|
However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call).
|
|
12
12
|
|
|
@@ -40,11 +40,11 @@ const { data: orders } = await useAPI('/orders')
|
|
|
40
40
|
</script>
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
:read-more{to="/docs/
|
|
43
|
+
:read-more{to="/docs/api/composables/create-use-fetch"}
|
|
44
44
|
|
|
45
45
|
## Recipe: Custom `$fetch` Instance
|
|
46
46
|
|
|
47
|
-
If you need lower-level control, you can create a custom `$fetch` instance with a [Nuxt plugin](/docs/
|
|
47
|
+
If you need lower-level control, you can create a custom `$fetch` instance with a [Nuxt plugin](/docs/directory-structure/app/plugins) and either use it with `useAsyncData` directly or pass it to `createUseFetch`.
|
|
48
48
|
|
|
49
49
|
::note
|
|
50
50
|
`$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).
|
|
@@ -86,9 +86,9 @@ const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
|
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
::callout
|
|
89
|
-
Wrapping with [`useAsyncData`](/docs/
|
|
89
|
+
Wrapping with [`useAsyncData`](/docs/api/composables/use-async-data) **avoids double data fetching when doing server-side rendering** (server & client on hydration).
|
|
90
90
|
::
|
|
91
91
|
|
|
92
|
-
:link-example{to="/docs/
|
|
92
|
+
:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
|
|
93
93
|
|
|
94
94
|
:video-accordion{title="Watch a video about custom $fetch and Repository Pattern in Nuxt" videoId="jXH8Tr-exhI"}
|
|
@@ -155,7 +155,7 @@ export default defineEventHandler(async (event) => {
|
|
|
155
155
|
|
|
156
156
|
## Protect App Routes
|
|
157
157
|
|
|
158
|
-
Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](
|
|
158
|
+
Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](/docs/directory-structure/app/middleware) to protect the route on the client side and redirect users to the login page.
|
|
159
159
|
|
|
160
160
|
`nuxt-auth-utils` provides a convenient `useUserSession` composable which we'll use to check if the user is logged in, and redirect them if they are not.
|
|
161
161
|
|
|
@@ -176,7 +176,7 @@ export default defineNuxtRouteMiddleware(() => {
|
|
|
176
176
|
|
|
177
177
|
Now that we have our app middleware to protect our routes, we can use it on our home page that display our authenticated user information. If the user is not authenticated, they will be redirected to the login page.
|
|
178
178
|
|
|
179
|
-
We'll use [`definePageMeta`](/docs/
|
|
179
|
+
We'll use [`definePageMeta`](/docs/api/utils/define-page-meta) to apply the middleware to the route that we want to protect.
|
|
180
180
|
|
|
181
181
|
```vue [app/pages/index.vue]
|
|
182
182
|
<script setup lang="ts">
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 'Mostly-Static Sites'
|
|
3
|
+
description: 'Ship near-zero JavaScript for content and marketing sites while keeping islands of interactivity.'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
By default, Nuxt server-renders a page and then hydrates all of it. For a page that is 95% static text and images, that hydration JavaScript is mostly overhead: it delays interactivity and competes with your content for bandwidth and CPU, which can hurt metrics like mobile PageSpeed scores.
|
|
7
|
+
|
|
8
|
+
Nuxt has the pieces to avoid paying that cost where you don't need it. This recipe combines them:
|
|
9
|
+
|
|
10
|
+
1. **Prerender** your content routes at build time.
|
|
11
|
+
2. **Drop the scripts** on those routes with the `noScripts` route rule.
|
|
12
|
+
3. Use **server components** for widgets that need server rendering but no interactivity.
|
|
13
|
+
4. Use **lazy hydration** on routes that keep their scripts, so interactivity is paid for only when needed.
|
|
14
|
+
|
|
15
|
+
## Prerender and Drop Scripts
|
|
16
|
+
|
|
17
|
+
For routes that have no client-side interactivity at all, combine `prerender` and `noScripts` in [`routeRules`](/docs/guide/concepts/rendering#hybrid-rendering):
|
|
18
|
+
|
|
19
|
+
```ts twoslash [nuxt.config.ts]
|
|
20
|
+
export default defineNuxtConfig({
|
|
21
|
+
routeRules: {
|
|
22
|
+
'/blog/**': { prerender: true, noScripts: true },
|
|
23
|
+
'/about': { prerender: true, noScripts: true },
|
|
24
|
+
},
|
|
25
|
+
})
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
These routes are rendered to plain HTML at build time, and the rendered pages omit the Nuxt entry scripts, import map, payload script and JS resource hints. CSS is still included. The result is a page with effectively zero JavaScript cost.
|
|
29
|
+
|
|
30
|
+
::read-more{to="/docs/guide/going-further/features#noscripts"}
|
|
31
|
+
Read more about exactly what `noScripts` omits, and the app-wide `features.noScripts` option.
|
|
32
|
+
::
|
|
33
|
+
|
|
34
|
+
::important
|
|
35
|
+
A `noScripts` page does not hydrate. Nothing on it is interactive: no `@click` handlers, no `<NuxtLink>` prefetching (links still work as plain `<a>` tags), no client-side navigation away from the page. Only use it on routes where that is what you want.
|
|
36
|
+
::
|
|
37
|
+
|
|
38
|
+
## Navigating to and from Script-Free Routes
|
|
39
|
+
|
|
40
|
+
Because a `noScripts` page has no client-side router, every navigation to or from one is a full-page load. Nuxt handles both directions of that for you:
|
|
41
|
+
|
|
42
|
+
- Navigating **from** a scripted route **to** a `noScripts` route (with `navigateTo`, `<NuxtLink>`, or `router.push`) triggers a document load, so the target is served script-free by the server rather than rendered by the client-side router.
|
|
43
|
+
- Because those routes are never rendered on the client, their page components are dropped from the client bundle when the route rules covering them can be resolved at build time.
|
|
44
|
+
- Both scripted and script-free pages emit a declarative [speculation rules](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) tag so supporting browsers prefetch and prerender the target before the user follows a link. This runs no JavaScript on the page itself, and the rules are scoped to your page routes, so a link to a server route such as `/logout` is never speculatively fetched.
|
|
45
|
+
|
|
46
|
+
With [experimental view transitions](/docs/getting-started/transitions#view-transitions-api-experimental) enabled, these pages also opt into cross-document view transitions, so a full-page navigation animates rather than flashing:
|
|
47
|
+
|
|
48
|
+
```ts twoslash [nuxt.config.ts]
|
|
49
|
+
export default defineNuxtConfig({
|
|
50
|
+
experimental: {
|
|
51
|
+
viewTransition: true,
|
|
52
|
+
},
|
|
53
|
+
})
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Islands for Server-Rendered Widgets
|
|
57
|
+
|
|
58
|
+
Some parts of a static page still benefit from being components with real logic behind them: rendered markdown, syntax-highlighted code, CMS content. Use [server components](/docs/guide/concepts/server-components) for these. They render on the server, and their dependencies never reach the client bundle:
|
|
59
|
+
|
|
60
|
+
```bash [Directory Structure]
|
|
61
|
+
-| app/
|
|
62
|
+
---| components/
|
|
63
|
+
-----| HighlightedMarkdown.server.vue
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```vue [app/pages/blog/[slug\\].vue]
|
|
67
|
+
<template>
|
|
68
|
+
<article>
|
|
69
|
+
<h1>{{ post.title }}</h1>
|
|
70
|
+
<HighlightedMarkdown :markdown="post.body" />
|
|
71
|
+
</article>
|
|
72
|
+
</template>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Static islands like this work fine on `noScripts` routes, since their HTML is embedded at render time.
|
|
76
|
+
|
|
77
|
+
::warning
|
|
78
|
+
Fully interactive widgets inside islands (components marked with [`nuxt-client`](/docs/guide/concepts/server-components#selective-hydration-with-nuxt-client), or interactive island slots) do **not** work on a `noScripts` route. Island teleports are relocated into place by a small inline script before hydration; with scripts disabled, that relocation cannot run and nothing hydrates. If a page needs even one interactive widget, keep scripts on that route and use lazy hydration instead.
|
|
79
|
+
::
|
|
80
|
+
|
|
81
|
+
## Lazy Hydration for the Rest
|
|
82
|
+
|
|
83
|
+
For routes that need some interactivity, keep scripts enabled but control *when* components hydrate using [lazy hydration](/docs/directory-structure/app/components#delayed-or-lazy-hydration):
|
|
84
|
+
|
|
85
|
+
```vue [app/pages/index.vue]
|
|
86
|
+
<template>
|
|
87
|
+
<div>
|
|
88
|
+
<HeroSection />
|
|
89
|
+
<!-- static content that never needs to become interactive -->
|
|
90
|
+
<LazyTestimonials hydrate-never />
|
|
91
|
+
<!-- hydrate only when scrolled into view -->
|
|
92
|
+
<LazyNewsletterSignup hydrate-on-visible />
|
|
93
|
+
<!-- hydrate when the browser is idle -->
|
|
94
|
+
<LazyCookieBanner hydrate-on-idle />
|
|
95
|
+
</div>
|
|
96
|
+
</template>
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`hydrate-never` is particularly useful on content sites: the component's HTML is server-rendered, but it is never hydrated, so its JavaScript is never executed (though prop changes will still trigger hydration).
|
|
100
|
+
|
|
101
|
+
## Putting It Together
|
|
102
|
+
|
|
103
|
+
A typical mostly-static site ends up with:
|
|
104
|
+
|
|
105
|
+
```ts twoslash [nuxt.config.ts]
|
|
106
|
+
export default defineNuxtConfig({
|
|
107
|
+
routeRules: {
|
|
108
|
+
// pure content: prerendered, zero JS
|
|
109
|
+
'/': { prerender: true, noScripts: true },
|
|
110
|
+
'/blog/**': { prerender: true, noScripts: true },
|
|
111
|
+
// pages with an interactive widget: prerendered, scripts kept
|
|
112
|
+
'/contact': { prerender: true },
|
|
113
|
+
},
|
|
114
|
+
})
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- content routes ship plain HTML and CSS, and navigation to them is a speculatively prefetched document load
|
|
118
|
+
- islands (`.server.vue` components) handle server-rendered widgets everywhere, keeping heavy dependencies out of the client bundle
|
|
119
|
+
- the few interactive routes keep scripts, with `hydrate-on-visible` / `hydrate-on-idle` / `hydrate-never` limiting how much work the browser does up front
|
|
120
|
+
|
|
121
|
+
::read-more{to="/docs/getting-started/prerendering"}
|
|
122
|
+
Read more about prerendering, including selective prerendering and payload extraction.
|
|
123
|
+
::
|
|
124
|
+
|
|
125
|
+
::read-more{to="/docs/guide/best-practices/performance"}
|
|
126
|
+
Read more general performance best practices for Nuxt apps.
|
|
127
|
+
::
|
|
@@ -57,6 +57,6 @@ await nuxtApp.callHook('app:user:registered', {
|
|
|
57
57
|
You can inspect all events using the **Nuxt DevTools** Hooks panel.
|
|
58
58
|
::
|
|
59
59
|
|
|
60
|
-
::read-more{to="/docs/
|
|
60
|
+
::read-more{to="/docs/guide/going-further/hooks"}
|
|
61
61
|
Learn more about Nuxt's built-in hooks and how to extend them
|
|
62
62
|
::
|