@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
@@ -67,7 +67,10 @@ For static files in the `/public` directory, such as PDFs or images, use the `ex
67
67
 
68
68
  ```vue [app/pages/index.vue]
69
69
  <template>
70
- <NuxtLink to="/example-report.pdf" external>
70
+ <NuxtLink
71
+ to="/example-report.pdf"
72
+ external
73
+ >
71
74
  Download Report
72
75
  </NuxtLink>
73
76
  </template>
@@ -79,7 +82,10 @@ When pointing to a different application on the same domain, using the `external
79
82
 
80
83
  ```vue [app/pages/index.vue]
81
84
  <template>
82
- <NuxtLink to="/another-app" external>
85
+ <NuxtLink
86
+ to="/another-app"
87
+ external
88
+ >
83
89
  Go to Another App
84
90
  </NuxtLink>
85
91
  </template>
@@ -117,12 +123,18 @@ When you need to overwrite this behavior you can use the `rel` or `noRel` props.
117
123
  </NuxtLink>
118
124
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->
119
125
 
120
- <NuxtLink to="https://discord.nuxtjs.org" rel="noopener">
126
+ <NuxtLink
127
+ to="https://discord.nuxtjs.org"
128
+ rel="noopener"
129
+ >
121
130
  Nuxt Discord
122
131
  </NuxtLink>
123
132
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->
124
133
 
125
- <NuxtLink to="/about" target="_blank">About page</NuxtLink>
134
+ <NuxtLink
135
+ to="/about"
136
+ target="_blank"
137
+ >About page</NuxtLink>
126
138
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
127
139
  </template>
128
140
  ```
@@ -131,7 +143,10 @@ A `noRel` prop can be used to prevent the default `rel` attribute from being add
131
143
 
132
144
  ```vue [app/app.vue]
133
145
  <template>
134
- <NuxtLink to="https://github.com/nuxt" no-rel>
146
+ <NuxtLink
147
+ to="https://github.com/nuxt"
148
+ no-rel
149
+ >
135
150
  Nuxt GitHub
136
151
  </NuxtLink>
137
152
  <!-- <a href="https://github.com/nuxt">...</a> -->
@@ -147,8 +162,13 @@ A `noRel` prop can be used to prevent the default `rel` attribute from being add
147
162
  Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn't busy and skips prefetching if your connection is offline or if you only have 2g connection.
148
163
 
149
164
  ```vue [app/pages/index.vue]
150
- <NuxtLink to="/about" no-prefetch>About page not pre-fetched</NuxtLink>
151
- <NuxtLink to="/about" :prefetch="false">About page not pre-fetched</NuxtLink>
165
+ <NuxtLink to="/about" no-prefetch>
166
+ About page not pre-fetched
167
+ </NuxtLink>
168
+
169
+ <NuxtLink to="/about" :prefetch="false">
170
+ About page not pre-fetched
171
+ </NuxtLink>
152
172
  ```
153
173
 
154
174
  ### Custom Prefetch Triggers
@@ -238,7 +258,7 @@ When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink`
238
258
  - `href`: An alias for `to`. If used with `to`, `href` will be ignored
239
259
  - `noRel`: If set to `true`, no `rel` attribute will be added to the external link
240
260
  - `external`: Forces the link to be rendered as an `<a>` tag instead of a Vue Router `RouterLink`.
241
- - `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/api/nuxt-config#crossoriginprefetch)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/api/nuxt-config#crossoriginprefetch) config.
261
+ - `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/api/nuxt-config#crossoriginprefetch)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/api/nuxt-config#crossoriginprefetch) config.
242
262
  - `prefetchOn`: Allows custom control of when to prefetch links. Possible options are `interaction` and `visibility` (default). You can also pass an object for full control, for example: `{ interaction: true, visibility: true }`. This prop is only used when `prefetch` is enabled (default) and `noPrefetch` is not set.
243
263
  - `noPrefetch`: Disables prefetching.
244
264
  - `prefetchedClass`: A class to apply to links that have been prefetched.
@@ -249,14 +269,14 @@ When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink`
249
269
  - `rel`: A `rel` attribute value to apply on the link. Defaults to `"noopener noreferrer"` for external links.
250
270
 
251
271
  ::tip
252
- Defaults can be overwritten, see [overwriting defaults](#overwriting-defaults) if you want to change them.
272
+ Defaults can be overwritten, see [overwriting defaults](/docs/4.x/api/components/nuxt-link#overwriting-defaults) if you want to change them.
253
273
  ::
254
274
 
255
275
  ## Overwriting Defaults
256
276
 
257
277
  ### In Nuxt Config
258
278
 
259
- You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/api/nuxt-config#defaults)
279
+ You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/api/nuxt-config#defaults)
260
280
 
261
281
  ::important
262
282
  These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
@@ -273,12 +293,12 @@ export default defineNuxtConfig({
273
293
  activeClass: 'router-link-active',
274
294
  exactActiveClass: 'router-link-exact-active',
275
295
  prefetchedClass: undefined, // can be any valid string class name
276
- trailingSlash: undefined // can be 'append' or 'remove'
296
+ trailingSlash: undefined, // can be 'append' or 'remove'
277
297
  prefetch: true,
278
- prefetchOn: { visibility: true }
279
- }
280
- }
281
- }
298
+ prefetchOn: { visibility: true },
299
+ },
300
+ },
301
+ },
282
302
  })
283
303
  ```
284
304
 
@@ -286,7 +306,7 @@ export default defineNuxtConfig({
286
306
 
287
307
  You can overwrite `<NuxtLink>` defaults by creating your own link component using `defineNuxtLink`.
288
308
 
289
- ```js [app/components/MyNuxtLink.ts]
309
+ ```ts [app/components/MyNuxtLink.ts]
290
310
  export default defineNuxtLink({
291
311
  componentName: 'MyNuxtLink',
292
312
  /* see signature below for more */
@@ -299,10 +319,10 @@ You can then use `<MyNuxtLink />` component as usual with your new defaults.
299
319
 
300
320
  ```ts
301
321
  interface NuxtLinkOptions {
302
- componentName?: string;
303
- externalRelAttribute?: string;
304
- activeClass?: string;
305
- exactActiveClass?: string;
322
+ componentName?: string
323
+ externalRelAttribute?: string
324
+ activeClass?: string
325
+ exactActiveClass?: string
306
326
  trailingSlash?: 'append' | 'remove'
307
327
  prefetch?: boolean
308
328
  prefetchedClass?: string
@@ -311,7 +331,7 @@ interface NuxtLinkOptions {
311
331
  interaction: boolean
312
332
  }>
313
333
  }
314
- function defineNuxtLink(options: NuxtLinkOptions): Component {}
334
+ function defineNuxtLink (options: NuxtLinkOptions): Component {}
315
335
  ```
316
336
 
317
337
  - `componentName`: A name for the component. Default is `NuxtLink`.
@@ -323,4 +343,4 @@ function defineNuxtLink(options: NuxtLinkOptions): Component {}
323
343
  - `prefetchOn`: Granular control of which prefetch strategies to apply by default.
324
344
  - `prefetchedClass`: A default class to apply to links that have been prefetched.
325
345
 
326
- :link-example{to="/docs/examples/routing/pages"}
346
+ :link-example{to="/docs/4.x/examples/routing/pages"}
@@ -10,7 +10,7 @@ links:
10
10
 
11
11
  ## Usage
12
12
 
13
- Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`app/layouts/`](/docs/guide/directory-structure/app/layouts).
13
+ Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts).
14
14
 
15
15
  ```vue [app/app.vue]
16
16
  <template>
@@ -21,7 +21,7 @@ Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/guide/directory-structur
21
21
  </template>
22
22
  ```
23
23
 
24
- :link-example{to="/docs/examples/routing/pages"}
24
+ :link-example{to="/docs/4.x/examples/routing/pages"}
25
25
 
26
26
  ## Slots
27
27
 
@@ -42,7 +42,7 @@ To achieve full customization, you can implement your own one based on [its sour
42
42
  ::
43
43
 
44
44
  ::note
45
- You can hook into the underlying indicator instance using [the `useLoadingIndicator` composable](/docs/api/composables/use-loading-indicator), which will allow you to trigger start/finish events yourself.
45
+ You can hook into the underlying indicator instance using [the `useLoadingIndicator` composable](/docs/4.x/api/composables/use-loading-indicator), which will allow you to trigger start/finish events yourself.
46
46
  ::
47
47
 
48
48
  ::tip
@@ -29,19 +29,21 @@ The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/c
29
29
  - `#error`: Specify a fallback content to display in case of error.
30
30
 
31
31
  ```vue
32
- <template>
33
- <NuxtErrorBoundary>
34
- <!-- ... -->
35
- <template #error="{ error, clearError }">
36
- <p>An error occurred: {{ error }}</p>
32
+ <template>
33
+ <NuxtErrorBoundary>
34
+ <!-- ... -->
35
+ <template #error="{ error, clearError }">
36
+ <p>An error occurred: {{ error }}</p>
37
37
 
38
- <button @click="clearError">Clear error</button>
39
- </template>
40
- </NuxtErrorBoundary>
41
- </template>
38
+ <button @click="clearError">
39
+ Clear error
40
+ </button>
41
+ </template>
42
+ </NuxtErrorBoundary>
43
+ </template>
42
44
  ```
43
45
 
44
- :read-more{to="/docs/getting-started/error-handling"}
46
+ :read-more{to="/docs/4.x/getting-started/error-handling"}
45
47
 
46
48
  ## Examples
47
49
 
@@ -24,8 +24,8 @@ Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script
24
24
  ## Type
25
25
 
26
26
  ```ts [Signature]
27
- export function onPrehydrate(callback: (el: HTMLElement) => void): void
28
- export function onPrehydrate(callback: string | ((el: HTMLElement) => void), key?: string): undefined | string
27
+ export function onPrehydrate (callback: (el: HTMLElement) => void): void
28
+ export function onPrehydrate (callback: string | ((el: HTMLElement) => void), key?: string): undefined | string
29
29
  ```
30
30
 
31
31
  ## Parameters
@@ -16,4 +16,4 @@ const appConfig = useAppConfig()
16
16
  console.log(appConfig)
17
17
  ```
18
18
 
19
- :read-more{to="/docs/guide/directory-structure/app-config"}
19
+ :read-more{to="/docs/4.x/guide/directory-structure/app-config"}
@@ -11,7 +11,7 @@ links:
11
11
  Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously.
12
12
 
13
13
  ::note
14
- [`useAsyncData`](/docs/api/composables/use-async-data) is a composable meant to be called directly in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context). It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates.
14
+ [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a composable meant to be called directly in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context). It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates.
15
15
  ::
16
16
 
17
17
  ## Usage
@@ -20,13 +20,13 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
20
20
  <script setup lang="ts">
21
21
  const { data, status, error, refresh, clear } = await useAsyncData(
22
22
  'mountains',
23
- () => $fetch('https://api.nuxtjs.dev/mountains')
23
+ () => $fetch('https://api.nuxtjs.dev/mountains'),
24
24
  )
25
25
  </script>
26
26
  ```
27
27
 
28
28
  ::warning
29
- If you're using a custom useAsyncData wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/guide/recipes/custom-usefetch#custom-usefetch) for more information on how to make a custom async data fetcher.
29
+ If you're using a custom useAsyncData wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata) for more information on how to make a custom async data fetcher.
30
30
  ::
31
31
 
32
32
  ::note
@@ -44,11 +44,11 @@ const { data: posts } = await useAsyncData(
44
44
  'posts',
45
45
  () => $fetch('https://fakeApi.com/posts', {
46
46
  params: {
47
- page: page.value
48
- }
47
+ page: page.value,
48
+ },
49
49
  }), {
50
- watch: [page]
51
- }
50
+ watch: [page],
51
+ },
52
52
  )
53
53
  </script>
54
54
  ```
@@ -65,23 +65,23 @@ const userId = computed(() => `user-${route.params.id}`)
65
65
  // When the route changes and userId updates, the data will be automatically refetched
66
66
  const { data: user } = useAsyncData(
67
67
  userId,
68
- () => fetchUserById(route.params.id)
68
+ () => fetchUserById(route.params.id),
69
69
  )
70
70
  </script>
71
71
  ```
72
72
 
73
73
  ::warning
74
- [`useAsyncData`](/docs/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/api/composables/use-async-data).
74
+ [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
75
75
  ::
76
76
 
77
- :read-more{to="/docs/getting-started/data-fetching#useasyncdata"}
77
+ :read-more{to="/docs/4.x/getting-started/data-fetching#useasyncdata"}
78
78
 
79
79
  ## Params
80
80
 
81
81
  - `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
82
82
  - `handler`: an asynchronous function that must return a truthy value (for example, it should not be `undefined` or `null`) or the request may be duplicated on the client side.
83
83
  ::warning
84
- The `handler` function should be **side-effect free** to ensure predictable behavior during SSR and CSR hydration. If you need to trigger side effects, use the [`callOnce`](/docs/api/utils/call-once) utility to do so.
84
+ The `handler` function should be **side-effect free** to ensure predictable behavior during SSR and CSR hydration. If you need to trigger side effects, use the [`callOnce`](/docs/4.x/api/utils/call-once) utility to do so.
85
85
  ::
86
86
  - `options`:
87
87
  - `server`: whether to fetch the data on the server (defaults to `true`)
@@ -91,8 +91,8 @@ The `handler` function should be **side-effect free** to ensure predictable beha
91
91
  - `transform`: a function that can be used to alter `handler` function result after resolving
92
92
  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
93
93
  ```ts
94
- const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
95
- ? nuxtApp.payload.data[key]
94
+ const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
95
+ ? nuxtApp.payload.data[key]
96
96
  : nuxtApp.static.data[key]
97
97
  ```
98
98
  Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled.
@@ -102,12 +102,13 @@ The `handler` function should be **side-effect free** to ensure predictable beha
102
102
  - `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
103
103
  - `cancel` - cancels existing requests when a new one is made
104
104
  - `defer` - does not make new requests at all if there is a pending request
105
+ - `timeout` - a number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout)
105
106
 
106
107
  ::note
107
108
  Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the route before the data has been fetched. Consider using `lazy: true` and implementing a loading state instead for a snappier user experience.
108
109
  ::
109
110
 
110
- ::read-more{to="/docs/api/composables/use-lazy-async-data"}
111
+ ::read-more{to="/docs/4.x/api/composables/use-lazy-async-data"}
111
112
  You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `useAsyncData`.
112
113
  ::
113
114
 
@@ -143,7 +144,7 @@ const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { imm
143
144
  ```
144
145
 
145
146
  ::tip
146
- Keyed state created using `useAsyncData` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/api/composables/use-nuxt-data).
147
+ Keyed state created using `useAsyncData` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/4.x/api/composables/use-nuxt-data).
147
148
  ::
148
149
 
149
150
  ## Return Values
@@ -163,19 +164,19 @@ Keyed state created using `useAsyncData` can be retrieved across your Nuxt appli
163
164
  By default, Nuxt waits until a `refresh` is finished before it can be executed again.
164
165
 
165
166
  ::note
166
- If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `undefined` within `<script setup>`.
167
+ If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/4.x/api/composables/use-async-data) on the client side, `data` will remain `undefined` within `<script setup>`.
167
168
  ::
168
169
 
169
170
  ## Type
170
171
 
171
172
  ```ts [Signature]
172
- function useAsyncData<DataT, DataE>(
173
- handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
173
+ export function useAsyncData<DataT, DataE> (
174
+ handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
174
175
  options?: AsyncDataOptions<DataT>
175
176
  ): AsyncData<DataT, DataE>
176
- function useAsyncData<DataT, DataE>(
177
+ export function useAsyncData<DataT, DataE> (
177
178
  key: MaybeRefOrGetter<string>,
178
- handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
179
+ handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
179
180
  options?: AsyncDataOptions<DataT>
180
181
  ): Promise<AsyncData<DataT, DataE>>
181
182
 
@@ -190,6 +191,7 @@ type AsyncDataOptions<DataT> = {
190
191
  pick?: string[]
191
192
  watch?: MultiWatchSources | false
192
193
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
194
+ timeout?: number
193
195
  }
194
196
 
195
197
  type AsyncDataRequestContext = {
@@ -204,13 +206,15 @@ type AsyncData<DataT, ErrorT> = {
204
206
  clear: () => void
205
207
  error: Ref<ErrorT | undefined>
206
208
  status: Ref<AsyncDataRequestStatus>
207
- };
209
+ }
208
210
 
209
211
  interface AsyncDataExecuteOptions {
210
212
  dedupe?: 'cancel' | 'defer'
213
+ timeout?: number
214
+ signal?: AbortSignal
211
215
  }
212
216
 
213
217
  type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
214
218
  ```
215
219
 
216
- :read-more{to="/docs/getting-started/data-fetching"}
220
+ :read-more{to="/docs/4.x/getting-started/data-fetching"}
@@ -17,7 +17,7 @@ const cookie = useCookie(name, options)
17
17
  ```
18
18
 
19
19
  ::note
20
- `useCookie` only works in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
20
+ `useCookie` only works in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
21
21
  ::
22
22
 
23
23
  ::tip
@@ -40,7 +40,7 @@ export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & Co
40
40
 
41
41
  export interface CookieRef<T> extends Ref<T> {}
42
42
 
43
- export function useCookie<T = string | null | undefined>(
43
+ export function useCookie<T = string | null | undefined> (
44
44
  name: string,
45
45
  options?: CookieOptions<T>
46
46
  ): CookieRef<T>
@@ -59,7 +59,7 @@ Most of the options will be directly passed to the [cookie](https://github.com/j
59
59
  | `decode` | `(value: string) => T` | `decodeURIComponent` + [destr](https://github.com/unjs/destr). | Custom function to decode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br/> **Note:** If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value. |
60
60
  | `encode` | `(value: T) => string` | `JSON.stringify` + `encodeURIComponent` | Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value. |
61
61
  | `default` | `() => T \| Ref<T>` | `undefined` | Function returning the default value if the cookie does not exist. The function can also return a `Ref`. |
62
- | `watch` | `boolean \| 'shallow'` | `true` | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/api/utils/refresh-cookie). |
62
+ | `watch` | `boolean \| 'shallow'` | `true` | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/4.x/api/utils/refresh-cookie). |
63
63
  | `readonly` | `boolean` | `false` | If `true`, disables writing to the cookie. |
64
64
  | `maxAge` | `number` | `undefined` | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set. |
65
65
  | `expires` | `Date` | `undefined` | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
@@ -84,15 +84,21 @@ The example below creates a cookie called `counter`. If the cookie doesn't exist
84
84
  <script setup lang="ts">
85
85
  const counter = useCookie('counter')
86
86
 
87
- counter.value = counter.value || Math.round(Math.random() * 1000)
87
+ counter.value ||= Math.round(Math.random() * 1000)
88
88
  </script>
89
89
 
90
90
  <template>
91
91
  <div>
92
92
  <h1>Counter: {{ counter || '-' }}</h1>
93
- <button @click="counter = null">reset</button>
94
- <button @click="counter--">-</button>
95
- <button @click="counter++">+</button>
93
+ <button @click="counter = null">
94
+ reset
95
+ </button>
96
+ <button @click="counter--">
97
+ -
98
+ </button>
99
+ <button @click="counter++">
100
+ +
101
+ </button>
96
102
  </div>
97
103
  </template>
98
104
  ```
@@ -105,8 +111,8 @@ const user = useCookie(
105
111
  'userInfo',
106
112
  {
107
113
  default: () => ({ score: -1 }),
108
- watch: false
109
- }
114
+ watch: false,
115
+ },
110
116
  )
111
117
 
112
118
  if (user.value) {
@@ -128,20 +134,18 @@ const list = useCookie(
128
134
  'list',
129
135
  {
130
136
  default: () => [],
131
- watch: 'shallow'
132
- }
137
+ watch: 'shallow',
138
+ },
133
139
  )
134
140
 
135
- function add() {
141
+ function add () {
136
142
  list.value?.push(Math.round(Math.random() * 1000))
137
143
  // list cookie won't be updated with this change
138
144
  }
139
145
 
140
- function save() {
141
- if (list.value) {
142
- // the actual `list` cookie will be updated
143
- list.value = [...list.value]
144
- }
146
+ function save () {
147
+ // the actual `list` cookie will be updated
148
+ list.value &&= [...list.value]
145
149
  }
146
150
  </script>
147
151
 
@@ -149,8 +153,12 @@ function save() {
149
153
  <div>
150
154
  <h1>List</h1>
151
155
  <pre>{{ list }}</pre>
152
- <button @click="add">Add</button>
153
- <button @click="save">Save</button>
156
+ <button @click="add">
157
+ Add
158
+ </button>
159
+ <button @click="save">
160
+ Save
161
+ </button>
154
162
  </div>
155
163
  </template>
156
164
  ```
@@ -160,7 +168,7 @@ function save() {
160
168
  You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.
161
169
 
162
170
  ```ts [server/api/counter.ts]
163
- export default defineEventHandler(event => {
171
+ export default defineEventHandler((event) => {
164
172
  // Read counter cookie
165
173
  let counter = getCookie(event, 'counter') || 0
166
174
 
@@ -172,4 +180,4 @@ export default defineEventHandler(event => {
172
180
  })
173
181
  ```
174
182
 
175
- :link-example{to="/docs/examples/advanced/use-cookie"}
183
+ :link-example{to="/docs/4.x/examples/advanced/use-cookie"}
@@ -42,7 +42,7 @@ Returns a `Ref` containing the current Nuxt error (or `undefined` if there is no
42
42
 
43
43
  ## Example
44
44
 
45
- ```ts
45
+ ```vue
46
46
  <script setup lang="ts">
47
47
  const error = useError()
48
48
 
@@ -52,4 +52,4 @@ if (error.value) {
52
52
  </script>
53
53
  ```
54
54
 
55
- :read-more{to="/docs/getting-started/error-handling"}
55
+ :read-more{to="/docs/4.x/getting-started/error-handling"}