@nuxt/docs 4.1.2 → 4.2.0

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.
Files changed (201) hide show
  1. package/1.getting-started/01.introduction.md +6 -6
  2. package/1.getting-started/02.installation.md +3 -2
  3. package/1.getting-started/03.configuration.md +36 -36
  4. package/1.getting-started/04.views.md +9 -9
  5. package/1.getting-started/05.assets.md +15 -9
  6. package/1.getting-started/06.styling.md +58 -48
  7. package/1.getting-started/07.routing.md +17 -17
  8. package/1.getting-started/08.seo-meta.md +59 -46
  9. package/1.getting-started/09.transitions.md +49 -44
  10. package/1.getting-started/10.data-fetching.md +104 -81
  11. package/1.getting-started/11.state-management.md +26 -19
  12. package/1.getting-started/12.error-handling.md +22 -20
  13. package/1.getting-started/13.server.md +8 -8
  14. package/1.getting-started/14.layers.md +22 -16
  15. package/1.getting-started/15.prerendering.md +32 -32
  16. package/1.getting-started/16.deployment.md +10 -10
  17. package/1.getting-started/17.testing.md +44 -44
  18. package/1.getting-started/18.upgrade.md +241 -110
  19. package/2.guide/0.index.md +7 -7
  20. package/2.guide/{2.directory-structure → 1.directory-structure}/.navigation.yml +1 -1
  21. package/2.guide/{2.directory-structure → 1.directory-structure}/0.nuxt.md +3 -3
  22. package/2.guide/1.directory-structure/0.output.md +18 -0
  23. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/.navigation.yml +1 -1
  24. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.assets.md +4 -4
  25. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.components.md +45 -28
  26. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.composables.md +13 -13
  27. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.layouts.md +19 -15
  28. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.middleware.md +31 -25
  29. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.pages.md +39 -37
  30. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.plugins.md +25 -25
  31. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/1.utils.md +7 -7
  32. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/3.app-config.md +18 -18
  33. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/3.app.md +7 -7
  34. package/2.guide/{2.directory-structure → 1.directory-structure}/1.app/3.error.md +6 -6
  35. package/2.guide/{2.directory-structure → 1.directory-structure}/1.content.md +7 -4
  36. package/2.guide/{2.directory-structure → 1.directory-structure}/1.modules.md +8 -8
  37. package/2.guide/{2.directory-structure → 1.directory-structure}/1.node_modules.md +2 -2
  38. package/2.guide/{2.directory-structure → 1.directory-structure}/1.public.md +2 -2
  39. package/2.guide/{2.directory-structure → 1.directory-structure}/1.server.md +35 -35
  40. package/2.guide/{2.directory-structure → 1.directory-structure}/1.shared.md +7 -7
  41. package/2.guide/{2.directory-structure → 1.directory-structure}/2.env.md +8 -8
  42. package/2.guide/{2.directory-structure → 1.directory-structure}/2.gitignore.md +1 -1
  43. package/2.guide/{2.directory-structure → 1.directory-structure}/2.nuxtignore.md +5 -4
  44. package/2.guide/{2.directory-structure → 1.directory-structure}/2.nuxtrc.md +4 -4
  45. package/2.guide/{2.directory-structure → 1.directory-structure}/3.nuxt-config.md +3 -3
  46. package/2.guide/{2.directory-structure → 1.directory-structure}/3.package.md +1 -1
  47. package/2.guide/{2.directory-structure → 1.directory-structure}/3.tsconfig.md +3 -3
  48. package/2.guide/{1.concepts → 2.concepts}/1.auto-imports.md +22 -22
  49. package/2.guide/{1.concepts → 2.concepts}/10.nuxt-lifecycle.md +17 -17
  50. package/2.guide/{1.concepts → 2.concepts}/2.vuejs-development.md +13 -13
  51. package/2.guide/{1.concepts → 2.concepts}/3.rendering.md +24 -22
  52. package/2.guide/{1.concepts → 2.concepts}/4.server-engine.md +6 -6
  53. package/2.guide/{1.concepts → 2.concepts}/5.modules.md +5 -5
  54. package/2.guide/{1.concepts → 2.concepts}/7.esm.md +22 -16
  55. package/2.guide/{1.concepts → 2.concepts}/8.typescript.md +12 -12
  56. package/2.guide/3.going-further/1.events.md +3 -3
  57. package/2.guide/3.going-further/1.experimental-features.md +334 -85
  58. package/2.guide/3.going-further/1.features.md +58 -11
  59. package/2.guide/3.going-further/1.internals.md +25 -25
  60. package/2.guide/3.going-further/10.runtime-config.md +12 -12
  61. package/2.guide/3.going-further/11.nightly-release-channel.md +1 -1
  62. package/2.guide/3.going-further/2.hooks.md +14 -14
  63. package/2.guide/3.going-further/3.modules.md +126 -108
  64. package/2.guide/3.going-further/4.kit.md +7 -7
  65. package/2.guide/3.going-further/6.nuxt-app.md +8 -8
  66. package/2.guide/3.going-further/7.layers.md +76 -59
  67. package/2.guide/3.going-further/9.debugging.md +2 -2
  68. package/2.guide/4.recipes/1.custom-routing.md +30 -30
  69. package/2.guide/4.recipes/2.vite-plugin.md +45 -4
  70. package/2.guide/4.recipes/3.custom-usefetch.md +13 -13
  71. package/2.guide/4.recipes/4.sessions-and-authentication.md +35 -21
  72. package/2.guide/5.best-practices/hydration.md +4 -4
  73. package/2.guide/5.best-practices/performance.md +17 -17
  74. package/3.api/1.components/1.client-only.md +6 -3
  75. package/3.api/1.components/1.nuxt-client-fallback.md +10 -7
  76. package/3.api/1.components/10.nuxt-picture.md +1 -1
  77. package/3.api/1.components/11.teleports.md +5 -2
  78. package/3.api/1.components/12.nuxt-route-announcer.md +9 -9
  79. package/3.api/1.components/13.nuxt-time.md +49 -18
  80. package/3.api/1.components/2.nuxt-page.md +6 -6
  81. package/3.api/1.components/3.nuxt-layout.md +15 -10
  82. package/3.api/1.components/4.nuxt-link.md +42 -22
  83. package/3.api/1.components/5.nuxt-loading-indicator.md +3 -3
  84. package/3.api/1.components/6.nuxt-error-boundary.md +12 -10
  85. package/3.api/2.composables/on-prehydrate.md +2 -2
  86. package/3.api/2.composables/use-app-config.md +1 -1
  87. package/3.api/2.composables/use-async-data.md +26 -22
  88. package/3.api/2.composables/use-cookie.md +29 -21
  89. package/3.api/2.composables/use-error.md +2 -2
  90. package/3.api/2.composables/use-fetch.md +62 -32
  91. package/3.api/2.composables/use-head-safe.md +7 -7
  92. package/3.api/2.composables/use-head.md +5 -5
  93. package/3.api/2.composables/use-hydration.md +6 -6
  94. package/3.api/2.composables/use-lazy-async-data.md +4 -4
  95. package/3.api/2.composables/use-lazy-fetch.md +4 -4
  96. package/3.api/2.composables/use-loading-indicator.md +12 -12
  97. package/3.api/2.composables/use-nuxt-app.md +22 -22
  98. package/3.api/2.composables/use-nuxt-data.md +8 -8
  99. package/3.api/2.composables/use-preview-mode.md +15 -18
  100. package/3.api/2.composables/use-request-event.md +1 -1
  101. package/3.api/2.composables/use-request-fetch.md +3 -3
  102. package/3.api/2.composables/use-request-header.md +1 -1
  103. package/3.api/2.composables/use-request-headers.md +4 -4
  104. package/3.api/2.composables/use-request-url.md +1 -1
  105. package/3.api/2.composables/use-response-header.md +9 -10
  106. package/3.api/2.composables/use-route-announcer.md +4 -4
  107. package/3.api/2.composables/use-route.md +1 -1
  108. package/3.api/2.composables/use-router.md +10 -8
  109. package/3.api/2.composables/use-runtime-config.md +11 -11
  110. package/3.api/2.composables/use-runtime-hook.md +2 -2
  111. package/3.api/2.composables/use-seo-meta.md +4 -4
  112. package/3.api/2.composables/use-server-seo-meta.md +6 -6
  113. package/3.api/2.composables/use-state.md +5 -5
  114. package/3.api/3.utils/$fetch.md +10 -8
  115. package/3.api/3.utils/abort-navigation.md +3 -3
  116. package/3.api/3.utils/add-route-middleware.md +5 -5
  117. package/3.api/3.utils/call-once.md +6 -6
  118. package/3.api/3.utils/clear-error.md +3 -3
  119. package/3.api/3.utils/clear-nuxt-data.md +3 -3
  120. package/3.api/3.utils/clear-nuxt-state.md +3 -3
  121. package/3.api/3.utils/create-error.md +2 -2
  122. package/3.api/3.utils/define-lazy-hydration-component.md +13 -13
  123. package/3.api/3.utils/define-nuxt-component.md +5 -5
  124. package/3.api/3.utils/define-nuxt-plugin.md +13 -13
  125. package/3.api/3.utils/define-nuxt-route-middleware.md +5 -5
  126. package/3.api/3.utils/define-page-meta.md +23 -23
  127. package/3.api/3.utils/define-route-rules.md +7 -7
  128. package/3.api/3.utils/navigate-to.md +11 -11
  129. package/3.api/3.utils/prefetch-components.md +1 -1
  130. package/3.api/3.utils/preload-components.md +1 -1
  131. package/3.api/3.utils/preload-route-components.md +2 -2
  132. package/3.api/3.utils/prerender-routes.md +3 -3
  133. package/3.api/3.utils/refresh-cookie.md +4 -4
  134. package/3.api/3.utils/refresh-nuxt-data.md +12 -7
  135. package/3.api/3.utils/reload-nuxt-app.md +3 -3
  136. package/3.api/3.utils/set-page-layout.md +1 -1
  137. package/3.api/3.utils/set-response-status.md +3 -3
  138. package/3.api/3.utils/show-error.md +5 -5
  139. package/3.api/3.utils/update-app-config.md +4 -3
  140. package/3.api/4.commands/add.md +1 -1
  141. package/3.api/4.commands/analyze.md +2 -1
  142. package/3.api/4.commands/build.md +2 -1
  143. package/3.api/4.commands/dev.md +5 -4
  144. package/3.api/4.commands/generate.md +3 -2
  145. package/3.api/4.commands/init.md +3 -2
  146. package/3.api/4.commands/module.md +4 -4
  147. package/3.api/4.commands/prepare.md +7 -2
  148. package/3.api/4.commands/preview.md +5 -4
  149. package/3.api/4.commands/test.md +40 -0
  150. package/3.api/4.commands/typecheck.md +5 -3
  151. package/3.api/4.commands/upgrade.md +3 -3
  152. package/3.api/5.kit/1.modules.md +123 -37
  153. package/3.api/5.kit/10.runtime-config.md +1 -1
  154. package/3.api/5.kit/10.templates.md +8 -6
  155. package/3.api/5.kit/11.nitro.md +66 -62
  156. package/3.api/5.kit/12.resolving.md +2 -2
  157. package/3.api/5.kit/14.builder.md +61 -4
  158. package/3.api/5.kit/15.examples.md +5 -7
  159. package/3.api/5.kit/16.layers.md +26 -26
  160. package/3.api/5.kit/3.compatibility.md +14 -14
  161. package/3.api/5.kit/4.autoimports.md +13 -13
  162. package/3.api/5.kit/5.components.md +8 -7
  163. package/3.api/5.kit/6.context.md +3 -3
  164. package/3.api/5.kit/7.pages.md +7 -7
  165. package/3.api/5.kit/8.layout.md +2 -2
  166. package/3.api/5.kit/9.head.md +132 -0
  167. package/3.api/5.kit/9.plugins.md +5 -4
  168. package/3.api/6.advanced/1.hooks.md +5 -5
  169. package/3.api/6.advanced/2.import-meta.md +3 -3
  170. package/3.api/6.nuxt-config.md +365 -859
  171. package/3.api/index.md +7 -7
  172. package/5.community/2.getting-help.md +1 -1
  173. package/5.community/3.reporting-bugs.md +3 -3
  174. package/5.community/4.contribution.md +11 -11
  175. package/5.community/5.framework-contribution.md +4 -4
  176. package/5.community/6.roadmap.md +2 -2
  177. package/6.bridge/1.overview.md +13 -13
  178. package/6.bridge/10.configuration.md +2 -1
  179. package/6.bridge/2.typescript.md +3 -3
  180. package/6.bridge/3.bridge-composition-api.md +8 -8
  181. package/6.bridge/4.plugins-and-middleware.md +9 -9
  182. package/6.bridge/5.nuxt3-compatible-api.md +20 -17
  183. package/6.bridge/6.meta.md +20 -19
  184. package/6.bridge/7.runtime-config.md +1 -1
  185. package/6.bridge/8.nitro.md +3 -3
  186. package/6.bridge/9.vite.md +4 -4
  187. package/7.migration/1.overview.md +2 -2
  188. package/7.migration/10.bundling.md +1 -1
  189. package/7.migration/11.server.md +3 -3
  190. package/7.migration/2.configuration.md +23 -21
  191. package/7.migration/20.module-authors.md +7 -7
  192. package/7.migration/3.auto-imports.md +3 -3
  193. package/7.migration/4.meta.md +21 -18
  194. package/7.migration/5.plugins-and-middleware.md +8 -8
  195. package/7.migration/6.pages-and-layouts.md +28 -24
  196. package/7.migration/7.component-options.md +18 -18
  197. package/7.migration/8.runtime-config.md +7 -7
  198. package/package.json +1 -1
  199. package/2.guide/2.directory-structure/0.output.md +0 -18
  200. /package/2.guide/{1.concepts → 2.concepts}/.navigation.yml +0 -0
  201. /package/2.guide/{1.concepts → 2.concepts}/9.code-style.md +0 -0
@@ -0,0 +1,132 @@
1
+ ---
2
+ title: Head
3
+ description: Nuxt Kit provides utilities to help you manage head configuration in modules.
4
+ links:
5
+ - label: Source
6
+ icon: i-simple-icons-github
7
+ to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/head.ts
8
+ size: xs
9
+ ---
10
+
11
+ ## `setGlobalHead`
12
+
13
+ Sets global head configuration for your Nuxt application. This utility allows modules to programmatically configure meta tags, links, scripts, and other head elements that will be applied across all pages.
14
+
15
+ The provided head configuration will be merged with any existing head configuration using deep merging, with your provided values taking precedence.
16
+
17
+ ::tip
18
+ This is particularly useful for modules that need to inject global meta tags, stylesheets, or scripts into the application head.
19
+ ::
20
+
21
+ ### Type
22
+
23
+ ```ts twoslash
24
+ // @errors: 2391
25
+ // ---cut---
26
+ import type { SerializableHead } from '@unhead/vue/types'
27
+
28
+ interface AppHeadMetaObject extends SerializableHead {
29
+ charset?: string
30
+ viewport?: string
31
+ }
32
+
33
+ function setGlobalHead (head: AppHeadMetaObject): void
34
+ ```
35
+
36
+ ### Parameters
37
+
38
+ #### `head`
39
+
40
+ **Type**: `AppHeadMetaObject`
41
+
42
+ An object containing head configuration. All properties are optional and will be merged with existing configuration:
43
+
44
+ - `charset`: Character encoding for the document
45
+ - `viewport`: Viewport meta tag configuration
46
+ - `meta`: Array of meta tag objects
47
+ - `link`: Array of link tag objects (stylesheets, icons, etc.)
48
+ - `style`: Array of inline style tag objects
49
+ - `script`: Array of script tag objects
50
+ - `noscript`: Array of noscript tag objects
51
+ - `title`: Default page title
52
+ - `titleTemplate`: Template for formatting page titles
53
+ - `bodyAttrs`: Attributes to add to the `<body>` tag
54
+ - `htmlAttrs`: Attributes to add to the `<html>` tag
55
+
56
+ ### Examples
57
+
58
+ #### Adding Global Meta Tags
59
+
60
+ ```ts
61
+ import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
62
+
63
+ export default defineNuxtModule({
64
+ setup () {
65
+ setGlobalHead({
66
+ meta: [
67
+ { name: 'theme-color', content: '#ffffff' },
68
+ { name: 'author', content: 'Your Name' },
69
+ ],
70
+ })
71
+ },
72
+ })
73
+ ```
74
+
75
+ #### Injecting Global Stylesheets
76
+
77
+ ```ts
78
+ import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
79
+
80
+ export default defineNuxtModule({
81
+ setup () {
82
+ setGlobalHead({
83
+ link: [
84
+ {
85
+ rel: 'stylesheet',
86
+ href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
87
+ },
88
+ ],
89
+ })
90
+ },
91
+ })
92
+ ```
93
+
94
+ #### Adding Global Scripts
95
+
96
+ ```ts
97
+ import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
98
+
99
+ export default defineNuxtModule({
100
+ setup () {
101
+ setGlobalHead({
102
+ script: [
103
+ {
104
+ src: 'https://cdn.example.com/analytics.js',
105
+ async: true,
106
+ defer: true,
107
+ },
108
+ ],
109
+ })
110
+ },
111
+ })
112
+ ```
113
+
114
+ #### Setting HTML Attributes
115
+
116
+ ```ts
117
+ import { defineNuxtModule, setGlobalHead } from '@nuxt/kit'
118
+
119
+ export default defineNuxtModule({
120
+ setup () {
121
+ setGlobalHead({
122
+ htmlAttrs: {
123
+ lang: 'en',
124
+ dir: 'ltr',
125
+ },
126
+ bodyAttrs: {
127
+ class: 'custom-body-class',
128
+ },
129
+ })
130
+ },
131
+ })
132
+ ```
@@ -38,7 +38,7 @@ export default defineNuxtModule({
38
38
  ### Type
39
39
 
40
40
  ```ts
41
- function addPlugin(plugin: NuxtPlugin | string, options?: AddPluginOptions): NuxtPlugin
41
+ function addPlugin (plugin: NuxtPlugin | string, options?: AddPluginOptions): NuxtPlugin
42
42
  ```
43
43
 
44
44
  ### Parameters
@@ -128,7 +128,7 @@ export default defineNuxtPlugin({
128
128
  ### Type
129
129
 
130
130
  ```ts
131
- function addPluginTemplate(pluginOptions: NuxtPluginTemplate, options?: AddPluginOptions): NuxtPlugin
131
+ function addPluginTemplate (pluginOptions: NuxtPluginTemplate, options?: AddPluginOptions): NuxtPlugin
132
132
  ```
133
133
 
134
134
  ### Parameters
@@ -204,12 +204,13 @@ export default defineNuxtConfig({
204
204
 
205
205
  ```ts [#build/vue-app-config.mjs]
206
206
  import { defineNuxtPlugin } from '#app/nuxt'
207
+
207
208
  export default defineNuxtPlugin({
208
209
  name: 'nuxt:vue-app-config',
209
210
  enforce: 'pre',
210
211
  setup (nuxtApp) {
211
- nuxtApp.vueApp.config["idPrefix"] = "nuxt"
212
- }
212
+ nuxtApp.vueApp.config.idPrefix = 'nuxt'
213
+ },
213
214
  })
214
215
  ```
215
216
 
@@ -3,7 +3,7 @@ title: 'Lifecycle Hooks'
3
3
  description: Nuxt provides a powerful hooking system to expand almost every aspect using hooks.
4
4
  ---
5
5
 
6
- :read-more{to="/docs/guide/going-further/hooks"}
6
+ :read-more{to="/docs/4.x/guide/going-further/hooks"}
7
7
 
8
8
  ## App Hooks (runtime)
9
9
 
@@ -30,7 +30,7 @@ Hook | Arguments | Environment | Description
30
30
  `page:loading:end` | - | Client | Called after `page:finish`
31
31
  `page:transition:finish`| `pageComponent?` | Client | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) event.
32
32
  `dev:ssr-logs` | `logs` | Client | Called with an array of server-side logs that have been passed to the client (if `features.devLogs` is enabled).
33
- `page:view-transition:start` | `transition` | Client | Called after `document.startViewTransition` is called when [experimental viewTransition support is enabled](/docs/getting-started/transitions#view-transitions-api-experimental).
33
+ `page:view-transition:start` | `transition` | Client | Called after `document.startViewTransition` is called when [experimental viewTransition support is enabled](/docs/4.x/getting-started/transitions#view-transitions-api-experimental).
34
34
 
35
35
  ## Nuxt Hooks (build time)
36
36
 
@@ -46,7 +46,7 @@ Hook | Arguments | Description
46
46
  `modules:done` | - | Called during Nuxt initialization, after installing user modules.
47
47
  `app:resolve` | `app` | Called after resolving the `app` instance.
48
48
  `app:templates` | `app` | Called during `NuxtApp` generation, to allow customizing, modifying or adding new files to the build directory (either virtually or to written to `.nuxt`).
49
- `app:templatesGenerated` | `app` | Called after templates are compiled into the [virtual file system](/docs/guide/directory-structure/nuxt#virtual-file-system) (vfs).
49
+ `app:templatesGenerated` | `app` | Called after templates are compiled into the [virtual file system](/docs/4.x/guide/directory-structure/nuxt) (vfs).
50
50
  `build:before` | - | Called before Nuxt bundle builder.
51
51
  `build:done` | - | Called after Nuxt bundle builder is complete.
52
52
  `build:manifest` | `manifest` | Called during the manifest build by Vite and webpack. This allows customizing the manifest that Nitro will use to render `<script>` and `<link>` tags in the final HTML.
@@ -75,8 +75,8 @@ Hook | Arguments | Description
75
75
  `schema:beforeWrite` | `schema` | Called before writing the given schema.
76
76
  `schema:written` | - | Called after the schema is written.
77
77
  `vite:extend` | `viteBuildContext` | Allows extending Vite default context.
78
- `vite:extendConfig` | `viteInlineConfig, env` | Allows extending Vite default config.
79
- `vite:configResolved` | `viteInlineConfig, env` | Allows reading the resolved Vite config.
78
+ `vite:extendConfig` | `viteInlineConfig, env` | Allows extending Vite default config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
79
+ `vite:configResolved` | `viteInlineConfig, env` | Allows reading the resolved Vite config. **Deprecated in Nuxt 5+.** In Nuxt 5, this operates on a shared configuration rather than separate client/server configs.
80
80
  `vite:serverCreated` | `viteServer, env` | Called when the Vite server is created.
81
81
  `vite:compiled` | - | Called after Vite server is compiled.
82
82
  `webpack:config` | `webpackConfigs` | Called before configuring the webpack compiler.
@@ -49,12 +49,12 @@ const resolver = createResolver(import.meta.url)
49
49
 
50
50
  export default defineNuxtModule({
51
51
  meta: { name: 'myModule' },
52
- setup() {
52
+ setup () {
53
53
  addComponent({
54
54
  name: 'MyModuleComponent',
55
55
  // Resolves to '/modules/my-module/components/MyModuleComponent.vue'
56
- filePath: resolver.resolve('./components/MyModuleComponent.vue')
56
+ filePath: resolver.resolve('./components/MyModuleComponent.vue'),
57
57
  })
58
- }
58
+ },
59
59
  })
60
60
  ```