@nuxt/docs 4.1.3 → 4.2.1
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/02.installation.md +4 -4
- package/1.getting-started/03.configuration.md +4 -4
- package/1.getting-started/04.views.md +2 -2
- package/1.getting-started/05.assets.md +1 -1
- package/1.getting-started/06.styling.md +11 -11
- package/1.getting-started/07.routing.md +4 -0
- package/1.getting-started/09.transitions.md +6 -6
- package/1.getting-started/10.data-fetching.md +14 -14
- package/1.getting-started/11.state-management.md +2 -2
- package/1.getting-started/12.error-handling.md +4 -4
- package/1.getting-started/13.server.md +4 -4
- package/1.getting-started/14.layers.md +29 -10
- package/1.getting-started/17.testing.md +3 -3
- package/1.getting-started/18.upgrade.md +205 -48
- package/2.guide/1.directory-structure/1.app/1.components.md +4 -4
- package/2.guide/1.directory-structure/1.app/1.composables.md +1 -1
- package/2.guide/1.directory-structure/1.app/1.layouts.md +2 -2
- package/2.guide/1.directory-structure/1.app/1.middleware.md +4 -4
- package/2.guide/1.directory-structure/1.app/1.pages.md +13 -13
- package/2.guide/1.directory-structure/1.app/1.plugins.md +1 -5
- package/2.guide/1.directory-structure/1.node_modules.md +1 -1
- package/2.guide/1.directory-structure/1.public.md +1 -1
- package/2.guide/1.directory-structure/1.server.md +5 -5
- package/2.guide/1.directory-structure/2.env.md +1 -1
- package/2.guide/1.directory-structure/3.tsconfig.md +38 -7
- package/2.guide/2.concepts/1.auto-imports.md +2 -2
- package/2.guide/2.concepts/10.nuxt-lifecycle.md +3 -3
- package/2.guide/2.concepts/2.vuejs-development.md +3 -3
- package/2.guide/2.concepts/3.rendering.md +4 -4
- package/2.guide/2.concepts/7.esm.md +7 -3
- package/2.guide/2.concepts/8.typescript.md +15 -38
- package/2.guide/2.concepts/9.code-style.md +1 -1
- package/2.guide/3.going-further/1.experimental-features.md +94 -6
- package/2.guide/3.going-further/1.features.md +15 -3
- package/2.guide/3.going-further/1.internals.md +2 -2
- package/2.guide/3.going-further/2.hooks.md +1 -1
- package/2.guide/3.going-further/3.modules.md +112 -29
- package/2.guide/3.going-further/6.nuxt-app.md +5 -5
- package/2.guide/3.going-further/7.layers.md +46 -21
- package/2.guide/3.going-further/9.debugging.md +1 -1
- package/2.guide/4.recipes/1.custom-routing.md +4 -4
- package/2.guide/4.recipes/2.vite-plugin.md +41 -0
- package/2.guide/4.recipes/3.custom-usefetch.md +1 -1
- package/2.guide/5.best-practices/hydration.md +1 -1
- package/3.api/1.components/10.nuxt-picture.md +1 -1
- package/3.api/1.components/11.teleports.md +1 -1
- package/3.api/1.components/12.nuxt-route-announcer.md +1 -1
- package/3.api/1.components/13.nuxt-time.md +5 -1
- package/3.api/1.components/2.nuxt-page.md +1 -1
- package/3.api/1.components/4.nuxt-link.md +11 -11
- package/3.api/1.components/5.nuxt-loading-indicator.md +1 -1
- package/3.api/1.components/6.nuxt-error-boundary.md +1 -1
- package/3.api/2.composables/use-app-config.md +1 -1
- package/3.api/2.composables/use-async-data.md +80 -13
- package/3.api/2.composables/use-cookie.md +7 -7
- package/3.api/2.composables/use-fetch.md +6 -2
- package/3.api/2.composables/use-head-safe.md +37 -20
- package/3.api/2.composables/use-head.md +136 -36
- package/3.api/2.composables/use-hydration.md +24 -18
- package/3.api/2.composables/use-lazy-async-data.md +58 -9
- package/3.api/2.composables/use-lazy-fetch.md +65 -9
- package/3.api/2.composables/use-nuxt-app.md +7 -7
- package/3.api/2.composables/use-nuxt-data.md +1 -1
- package/3.api/2.composables/use-request-fetch.md +1 -1
- package/3.api/2.composables/use-route.md +1 -1
- package/3.api/2.composables/use-router.md +15 -15
- package/3.api/2.composables/use-runtime-hook.md +1 -1
- package/3.api/2.composables/use-state.md +1 -1
- package/3.api/3.utils/abort-navigation.md +2 -2
- package/3.api/3.utils/define-lazy-hydration-component.md +4 -4
- package/3.api/3.utils/define-nuxt-component.md +1 -1
- package/3.api/3.utils/define-nuxt-plugin.md +1 -1
- package/3.api/3.utils/define-nuxt-route-middleware.md +1 -1
- package/3.api/3.utils/define-page-meta.md +8 -8
- package/3.api/3.utils/navigate-to.md +5 -5
- package/3.api/3.utils/on-before-route-leave.md +1 -1
- package/3.api/3.utils/on-before-route-update.md +1 -1
- package/3.api/3.utils/refresh-cookie.md +1 -1
- package/3.api/3.utils/update-app-config.md +2 -2
- package/3.api/5.kit/1.modules.md +88 -2
- package/3.api/5.kit/11.nitro.md +4 -0
- package/3.api/5.kit/14.builder.md +66 -10
- package/3.api/5.kit/15.examples.md +3 -5
- package/3.api/5.kit/2.programmatic.md +2 -2
- package/3.api/5.kit/5.components.md +1 -0
- package/3.api/5.kit/9.head.md +132 -0
- package/3.api/6.advanced/1.hooks.md +7 -7
- package/3.api/6.nuxt-config.md +100 -29
- package/5.community/3.reporting-bugs.md +3 -3
- package/5.community/4.contribution.md +1 -1
- package/5.community/5.framework-contribution.md +8 -8
- package/5.community/6.roadmap.md +4 -4
- package/6.bridge/4.plugins-and-middleware.md +1 -1
- package/7.migration/2.configuration.md +2 -2
- package/7.migration/20.module-authors.md +1 -1
- package/7.migration/5.plugins-and-middleware.md +1 -1
- package/7.migration/6.pages-and-layouts.md +2 -2
- package/README.md +1 -1
- package/package.json +1 -1
|
@@ -8,15 +8,68 @@ links:
|
|
|
8
8
|
size: xs
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
By default, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
|
|
11
|
+
`useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
|
|
14
12
|
|
|
15
13
|
::note
|
|
16
|
-
|
|
14
|
+
By default, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` allows navigation to occur immediately while data fetching continues in the background.
|
|
17
15
|
::
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```vue [app/pages/index.vue]
|
|
20
|
+
<script setup lang="ts">
|
|
21
|
+
const { status, data: posts } = await useLazyAsyncData('posts', () => $fetch('/api/posts'))
|
|
22
|
+
</script>
|
|
23
|
+
|
|
24
|
+
<template>
|
|
25
|
+
<div>
|
|
26
|
+
<div v-if="status === 'pending'">
|
|
27
|
+
Loading...
|
|
28
|
+
</div>
|
|
29
|
+
<div v-else-if="status === 'error'">
|
|
30
|
+
Error loading posts
|
|
31
|
+
</div>
|
|
32
|
+
<div v-else>
|
|
33
|
+
{{ posts }}
|
|
34
|
+
</div>
|
|
35
|
+
</div>
|
|
36
|
+
</template>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
When using `useLazyAsyncData`, navigation will occur before fetching is complete. This means you must handle `pending` and `error` states directly within your component's template.
|
|
40
|
+
|
|
41
|
+
::warning
|
|
42
|
+
`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
|
|
43
|
+
::
|
|
44
|
+
|
|
45
|
+
## Type
|
|
46
|
+
|
|
47
|
+
```ts [Signature]
|
|
48
|
+
export function useLazyAsyncData<DataT, ErrorT> (
|
|
49
|
+
handler: (ctx?: NuxtApp) => Promise<DataT>,
|
|
50
|
+
options?: AsyncDataOptions<DataT>,
|
|
51
|
+
): AsyncData<DataT, ErrorT>
|
|
52
|
+
|
|
53
|
+
export function useLazyAsyncData<DataT, ErrorT> (
|
|
54
|
+
key: string,
|
|
55
|
+
handler: (ctx?: NuxtApp) => Promise<DataT>,
|
|
56
|
+
options?: AsyncDataOptions<DataT>,
|
|
57
|
+
): AsyncData<DataT, ErrorT>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
|
|
61
|
+
|
|
62
|
+
## Parameters
|
|
63
|
+
|
|
64
|
+
`useLazyAsyncData` accepts the same parameters as [`useAsyncData`](/docs/4.x/api/composables/use-async-data), with the `lazy` option automatically set to `true`.
|
|
65
|
+
|
|
66
|
+
:read-more{to="/docs/4.x/api/composables/use-async-data#parameters"}
|
|
67
|
+
|
|
68
|
+
## Return Values
|
|
69
|
+
|
|
70
|
+
`useLazyAsyncData` returns the same values as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
|
|
71
|
+
|
|
72
|
+
:read-more{to="/docs/4.x/api/composables/use-async-data#return-values"}
|
|
20
73
|
|
|
21
74
|
## Example
|
|
22
75
|
|
|
@@ -40,8 +93,4 @@ watch(count, (newCount) => {
|
|
|
40
93
|
</template>
|
|
41
94
|
```
|
|
42
95
|
|
|
43
|
-
::warning
|
|
44
|
-
`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
|
|
45
|
-
::
|
|
46
|
-
|
|
47
96
|
:read-more{to="/docs/4.x/getting-started/data-fetching"}
|
|
@@ -8,21 +8,81 @@ links:
|
|
|
8
8
|
size: xs
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
`useLazyFetch` provides a wrapper around [`useFetch`](/docs/4.x/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
By default, [`useFetch`](/docs/4.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` allows navigation to proceed immediately, with data being fetched in the background.
|
|
16
|
+
|
|
17
|
+
```vue [app/pages/index.vue]
|
|
18
|
+
<script setup lang="ts">
|
|
19
|
+
const { status, data: posts } = await useLazyFetch('/api/posts')
|
|
20
|
+
</script>
|
|
21
|
+
|
|
22
|
+
<template>
|
|
23
|
+
<div v-if="status === 'pending'">
|
|
24
|
+
Loading ...
|
|
25
|
+
</div>
|
|
26
|
+
<div v-else>
|
|
27
|
+
<div v-for="post in posts">
|
|
28
|
+
<!-- do something -->
|
|
29
|
+
</div>
|
|
30
|
+
</div>
|
|
31
|
+
</template>
|
|
32
|
+
```
|
|
14
33
|
|
|
15
34
|
::note
|
|
16
35
|
`useLazyFetch` has the same signature as [`useFetch`](/docs/4.x/api/composables/use-fetch).
|
|
17
36
|
::
|
|
18
37
|
|
|
38
|
+
::warning
|
|
39
|
+
Awaiting `useLazyFetch` only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you must handle the `pending` state in your component's template.
|
|
40
|
+
::
|
|
41
|
+
|
|
42
|
+
::warning
|
|
43
|
+
`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
|
|
44
|
+
::
|
|
45
|
+
|
|
46
|
+
## Type
|
|
47
|
+
|
|
48
|
+
```ts [Signature]
|
|
49
|
+
export function useLazyFetch<DataT, ErrorT> (
|
|
50
|
+
url: string | Request | Ref<string | Request> | (() => string | Request),
|
|
51
|
+
options?: UseFetchOptions<DataT>,
|
|
52
|
+
): Promise<AsyncData<DataT, ErrorT>>
|
|
53
|
+
```
|
|
54
|
+
|
|
19
55
|
::note
|
|
20
|
-
|
|
56
|
+
`useLazyFetch` is equivalent to `useFetch` with `lazy: true` option set. See [`useFetch`](/docs/4.x/api/composables/use-fetch) for full type definitions.
|
|
21
57
|
::
|
|
22
58
|
|
|
23
|
-
|
|
59
|
+
## Parameters
|
|
60
|
+
|
|
61
|
+
`useLazyFetch` accepts the same parameters as [`useFetch`](/docs/4.x/api/composables/use-fetch):
|
|
62
|
+
|
|
63
|
+
- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch.
|
|
64
|
+
- `options` (object): Same as [`useFetch` options](/docs/4.x/api/composables/use-fetch#parameters), with `lazy` automatically set to `true`.
|
|
65
|
+
|
|
66
|
+
:read-more{to="/docs/4.x/api/composables/use-fetch#parameters"}
|
|
24
67
|
|
|
25
|
-
##
|
|
68
|
+
## Return Values
|
|
69
|
+
|
|
70
|
+
Returns the same `AsyncData` object as [`useFetch`](/docs/4.x/api/composables/use-fetch):
|
|
71
|
+
|
|
72
|
+
| Name | Type | Description |
|
|
73
|
+
| --- | --- |--- |
|
|
74
|
+
| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
|
|
75
|
+
| `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. |
|
|
76
|
+
| `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
|
|
77
|
+
| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
|
|
78
|
+
| `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. |
|
|
79
|
+
| `clear` | `() => void` | Resets `data` to `undefined`, `error` to `undefined`, sets `status` to `idle`, and cancels any pending requests. |
|
|
80
|
+
|
|
81
|
+
:read-more{to="/docs/4.x/api/composables/use-fetch#return-values"}
|
|
82
|
+
|
|
83
|
+
## Examples
|
|
84
|
+
|
|
85
|
+
### Handling Pending State
|
|
26
86
|
|
|
27
87
|
```vue [app/pages/index.vue]
|
|
28
88
|
<script setup lang="ts">
|
|
@@ -48,8 +108,4 @@ watch(posts, (newPosts) => {
|
|
|
48
108
|
</template>
|
|
49
109
|
```
|
|
50
110
|
|
|
51
|
-
::note
|
|
52
|
-
`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
|
|
53
|
-
::
|
|
54
|
-
|
|
55
111
|
:read-more{to="/docs/4.x/getting-started/data-fetching"}
|
|
@@ -30,7 +30,7 @@ By default, the shared runtime context of Nuxt is namespaced under the [`buildId
|
|
|
30
30
|
|
|
31
31
|
### `provide (name, value)`
|
|
32
32
|
|
|
33
|
-
`nuxtApp` is a runtime context that you can extend using [Nuxt plugins](/docs/4.x/guide/directory-structure/plugins). Use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components.
|
|
33
|
+
`nuxtApp` is a runtime context that you can extend using [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins). Use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components.
|
|
34
34
|
|
|
35
35
|
`provide` function accepts `name` and `value` parameters.
|
|
36
36
|
|
|
@@ -46,7 +46,7 @@ As you can see in the example above, `$hello` has become the new and custom part
|
|
|
46
46
|
|
|
47
47
|
### `hook(name, cb)`
|
|
48
48
|
|
|
49
|
-
Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/docs/4.x/guide/directory-structure/plugins) to hook into the rendering lifecycle.
|
|
49
|
+
Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins) to hook into the rendering lifecycle.
|
|
50
50
|
|
|
51
51
|
`hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used when creating Nuxt plugins.
|
|
52
52
|
|
|
@@ -80,12 +80,12 @@ await nuxtApp.callHook('my-plugin:init')
|
|
|
80
80
|
|
|
81
81
|
### `vueApp`
|
|
82
82
|
|
|
83
|
-
`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application
|
|
83
|
+
`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application#application-api) that you can access through `nuxtApp`.
|
|
84
84
|
|
|
85
85
|
Some useful methods:
|
|
86
|
-
- [`component()`](https://vuejs.org/api/application
|
|
87
|
-
- [`directive()`](https://vuejs.org/api/application
|
|
88
|
-
- [`use()`](https://vuejs.org/api/application
|
|
86
|
+
- [`component()`](https://vuejs.org/api/application#app-component) - Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.
|
|
87
|
+
- [`directive()`](https://vuejs.org/api/application#app-directive) - Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed[(example)](/docs/4.x/guide/directory-structure/app/plugins#vue-directives).
|
|
88
|
+
- [`use()`](https://vuejs.org/api/application#app-use) - Installs a **[Vue.js Plugin](https://vuejs.org/guide/reusability/plugins)** [(example)](/docs/4.x/guide/directory-structure/app/plugins#vue-plugins).
|
|
89
89
|
|
|
90
90
|
:read-more{icon="i-simple-icons-vuedotjs" to="https://vuejs.org/api/application.html#application-api"}
|
|
91
91
|
|
|
@@ -108,7 +108,7 @@ Nuxt exposes the following properties through `ssrContext`:
|
|
|
108
108
|
::code-group
|
|
109
109
|
```vue [app/app.vue]
|
|
110
110
|
<script setup lang="ts">
|
|
111
|
-
const { data } = await useAsyncData('count', () => $fetch('/api/count'))
|
|
111
|
+
const { data } = await useAsyncData('count', (_nuxtApp, { signal }) => $fetch('/api/count', { signal }))
|
|
112
112
|
</script>
|
|
113
113
|
```
|
|
114
114
|
```ts [server/api/count.ts]
|
|
@@ -67,7 +67,7 @@ Optimistic Updates is a technique where the user interface is updated immediatel
|
|
|
67
67
|
```vue [app/pages/todos.vue]
|
|
68
68
|
<script setup lang="ts">
|
|
69
69
|
// We can access same data later using 'todos' key
|
|
70
|
-
const { data } = await useAsyncData('todos', () => $fetch('/api/todos'))
|
|
70
|
+
const { data } = await useAsyncData('todos', (_nuxtApp, { signal }) => $fetch('/api/todos', { signal }))
|
|
71
71
|
</script>
|
|
72
72
|
```
|
|
73
73
|
|
|
@@ -33,7 +33,7 @@ const { data: forwarded } = await useAsyncData(() => requestFetch('/api/cookies'
|
|
|
33
33
|
|
|
34
34
|
// This will NOT forward anything
|
|
35
35
|
// Result: { cookies: {} }
|
|
36
|
-
const { data: notForwarded } = await useAsyncData(() => $fetch('/api/cookies'))
|
|
36
|
+
const { data: notForwarded } = await useAsyncData((_nuxtApp, { signal }) => $fetch('/api/cookies', { signal }))
|
|
37
37
|
</script>
|
|
38
38
|
```
|
|
39
39
|
|
|
@@ -84,4 +84,4 @@ Read more about accessing the route in the middleware section.
|
|
|
84
84
|
|
|
85
85
|
Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` to affect the template can trigger hydration issues because this will include the fragment on client but not the server.
|
|
86
86
|
|
|
87
|
-
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/
|
|
87
|
+
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/routelocationnormalizedloaded"}
|
|
@@ -26,17 +26,17 @@ If you only need the router instance within your template, use `$router`:
|
|
|
26
26
|
|
|
27
27
|
If you have a `app/pages/` directory, `useRouter` is identical in behavior to the one provided by `vue-router`.
|
|
28
28
|
|
|
29
|
-
::read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/
|
|
29
|
+
::read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/router#Properties-currentRoute-" target="_blank"}
|
|
30
30
|
Read `vue-router` documentation about the `Router` interface.
|
|
31
31
|
::
|
|
32
32
|
|
|
33
33
|
## Basic Manipulation
|
|
34
34
|
|
|
35
|
-
- [`addRoute()`](https://router.vuejs.org/api/interfaces/
|
|
36
|
-
- [`removeRoute()`](https://router.vuejs.org/api/interfaces/
|
|
37
|
-
- [`getRoutes()`](https://router.vuejs.org/api/interfaces/
|
|
38
|
-
- [`hasRoute()`](https://router.vuejs.org/api/interfaces/
|
|
39
|
-
- [`resolve()`](https://router.vuejs.org/api/interfaces/
|
|
35
|
+
- [`addRoute()`](https://router.vuejs.org/api/interfaces/router#addRoute-): Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route.
|
|
36
|
+
- [`removeRoute()`](https://router.vuejs.org/api/interfaces/router#removeRoute-): Remove an existing route by its name.
|
|
37
|
+
- [`getRoutes()`](https://router.vuejs.org/api/interfaces/router#getRoutes-): Get a full list of all the route records.
|
|
38
|
+
- [`hasRoute()`](https://router.vuejs.org/api/interfaces/router#hasRoute-): Checks if a route with a given name exists.
|
|
39
|
+
- [`resolve()`](https://router.vuejs.org/api/interfaces/router#resolve-): Returns the normalized version of a route location. Also includes an `href` property that includes any existing base.
|
|
40
40
|
|
|
41
41
|
```ts [Example]
|
|
42
42
|
const router = useRouter()
|
|
@@ -49,16 +49,16 @@ router.resolve({ name: 'home' })
|
|
|
49
49
|
```
|
|
50
50
|
|
|
51
51
|
::note
|
|
52
|
-
`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/4.x/guide/directory-structure/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
|
|
52
|
+
`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
|
|
53
53
|
::
|
|
54
54
|
|
|
55
55
|
## Based on History API
|
|
56
56
|
|
|
57
|
-
- [`back()`](https://router.vuejs.org/api/interfaces/
|
|
58
|
-
- [`forward()`](https://router.vuejs.org/api/interfaces/
|
|
59
|
-
- [`go()`](https://router.vuejs.org/api/interfaces/
|
|
60
|
-
- [`push()`](https://router.vuejs.org/api/interfaces/
|
|
61
|
-
- [`replace()`](https://router.vuejs.org/api/interfaces/
|
|
57
|
+
- [`back()`](https://router.vuejs.org/api/interfaces/router#back-): Go back in history if possible, same as `router.go(-1)`.
|
|
58
|
+
- [`forward()`](https://router.vuejs.org/api/interfaces/router#forward-): Go forward in history if possible, same as `router.go(1)`.
|
|
59
|
+
- [`go()`](https://router.vuejs.org/api/interfaces/router#go-): Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`.
|
|
60
|
+
- [`push()`](https://router.vuejs.org/api/interfaces/router#push-): Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](/docs/4.x/api/utils/navigate-to) instead.**
|
|
61
|
+
- [`replace()`](https://router.vuejs.org/api/interfaces/router#replace-): Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](/docs/4.x/api/utils/navigate-to) instead.**
|
|
62
62
|
|
|
63
63
|
```ts [Example]
|
|
64
64
|
const router = useRouter()
|
|
@@ -84,10 +84,10 @@ However, Nuxt has a concept of **route middleware** that simplifies the implemen
|
|
|
84
84
|
|
|
85
85
|
## Promise and Error Handling
|
|
86
86
|
|
|
87
|
-
- [`isReady()`](https://router.vuejs.org/api/interfaces/
|
|
88
|
-
- [`onError`](https://router.vuejs.org/api/interfaces/
|
|
87
|
+
- [`isReady()`](https://router.vuejs.org/api/interfaces/router#isReady-): Returns a Promise that resolves when the router has completed the initial navigation.
|
|
88
|
+
- [`onError`](https://router.vuejs.org/api/interfaces/router#onError-): Adds an error handler that is called every time a non caught error happens during navigation.
|
|
89
89
|
|
|
90
|
-
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/
|
|
90
|
+
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/router#Methods-" title="Vue Router Docs" target="_blank"}
|
|
91
91
|
|
|
92
92
|
## Universal Router Instance
|
|
93
93
|
|
|
@@ -15,7 +15,7 @@ This composable is available in Nuxt v3.14+.
|
|
|
15
15
|
```ts [signature]
|
|
16
16
|
function useRuntimeHook<THookName extends keyof RuntimeNuxtHooks> (
|
|
17
17
|
name: THookName,
|
|
18
|
-
fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never
|
|
18
|
+
fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never,
|
|
19
19
|
): void
|
|
20
20
|
```
|
|
21
21
|
|
|
@@ -29,7 +29,7 @@ Because the data inside `useState` will be serialized to JSON, it is important t
|
|
|
29
29
|
|
|
30
30
|
## Using `shallowRef`
|
|
31
31
|
|
|
32
|
-
If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced
|
|
32
|
+
If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced#shallowref). This can improve performance when your state contains large objects and arrays.
|
|
33
33
|
|
|
34
34
|
```ts
|
|
35
35
|
const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
|
|
@@ -22,7 +22,7 @@ export function abortNavigation (err?: Error | string): false
|
|
|
22
22
|
|
|
23
23
|
### `err`
|
|
24
24
|
|
|
25
|
-
- **Type**: [`Error`](https://developer.mozilla.org/
|
|
25
|
+
- **Type**: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string`
|
|
26
26
|
|
|
27
27
|
Optional error to be thrown by `abortNavigation`.
|
|
28
28
|
|
|
@@ -60,7 +60,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
|
|
|
60
60
|
|
|
61
61
|
### `err` as an Error Object
|
|
62
62
|
|
|
63
|
-
You can pass the error as an [`Error`](https://developer.mozilla.org/
|
|
63
|
+
You can pass the error as an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, e.g. caught by the `catch`-block:
|
|
64
64
|
|
|
65
65
|
```ts [app/middleware/auth.ts]
|
|
66
66
|
export default defineNuxtRouteMiddleware((to, from) => {
|
|
@@ -42,7 +42,7 @@ Read more about the options for `hydrate-on-visible`.
|
|
|
42
42
|
::
|
|
43
43
|
|
|
44
44
|
::note
|
|
45
|
-
Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async
|
|
45
|
+
Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async#hydrate-on-visible).
|
|
46
46
|
::
|
|
47
47
|
|
|
48
48
|
### Idle Strategy
|
|
@@ -70,7 +70,7 @@ The `hydrateOnIdle` prop is optional. You can pass a positive number to specify
|
|
|
70
70
|
Idle strategy is for components that can be hydrated when the browser is idle.
|
|
71
71
|
|
|
72
72
|
::note
|
|
73
|
-
Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async
|
|
73
|
+
Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async#hydrate-on-idle).
|
|
74
74
|
::
|
|
75
75
|
|
|
76
76
|
### Interaction Strategy
|
|
@@ -99,7 +99,7 @@ const LazyHydrationMyComponent = defineLazyHydrationComponent(
|
|
|
99
99
|
The `hydrateOnInteraction` prop is optional. If you do not pass an event or a list of events, it defaults to hydrating on `pointerenter`, `click`, and `focus`.
|
|
100
100
|
|
|
101
101
|
::note
|
|
102
|
-
Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async
|
|
102
|
+
Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async#hydrate-on-interaction).
|
|
103
103
|
::
|
|
104
104
|
|
|
105
105
|
### Media Query Strategy
|
|
@@ -126,7 +126,7 @@ const LazyHydrationMyComponent = defineLazyHydrationComponent(
|
|
|
126
126
|
```
|
|
127
127
|
|
|
128
128
|
::note
|
|
129
|
-
Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async
|
|
129
|
+
Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async#hydrate-on-media-query).
|
|
130
130
|
::
|
|
131
131
|
|
|
132
132
|
### Time Strategy
|
|
@@ -9,7 +9,7 @@ links:
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
::note
|
|
12
|
-
`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general
|
|
12
|
+
`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general#definecomponent). `defineNuxtComponent()` wrapper also adds support for `asyncData` and `head` component options.
|
|
13
13
|
::
|
|
14
14
|
|
|
15
15
|
::note
|
|
@@ -42,7 +42,7 @@ interface ObjectPlugin<T> {
|
|
|
42
42
|
## Parameters
|
|
43
43
|
|
|
44
44
|
**plugin**: A plugin can be defined in two ways:
|
|
45
|
-
1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with
|
|
45
|
+
1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with a potential object with a [`provide`](/docs/4.x/guide/directory-structure/app/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance.
|
|
46
46
|
2. **Object Plugin**: An object that can include various properties to configure the plugin's behavior, such as `name`, `enforce`, `dependsOn`, `order`, `parallel`, `setup`, `hooks`, and `env`.
|
|
47
47
|
|
|
48
48
|
| Property | Type | Required | Description |
|
|
@@ -28,7 +28,7 @@ interface RouteMiddleware {
|
|
|
28
28
|
|
|
29
29
|
A function that takes two Vue Router's route location objects as parameters: the next route `to` as the first, and the current route `from` as the second.
|
|
30
30
|
|
|
31
|
-
Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/type-aliases/
|
|
31
|
+
Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/type-aliases/routelocationnormalized)**.
|
|
32
32
|
|
|
33
33
|
## Examples
|
|
34
34
|
|
|
@@ -62,7 +62,7 @@ interface PageMeta {
|
|
|
62
62
|
|
|
63
63
|
- **Type**: `string`
|
|
64
64
|
|
|
65
|
-
You may define a [custom regular expression](/docs/4.x/api/
|
|
65
|
+
You may define a [custom regular expression](/docs/4.x/api/utils/define-page-meta#using-a-custom-regular-expression) if you have a more complex pattern than can be expressed with the file name.
|
|
66
66
|
|
|
67
67
|
**`props`**
|
|
68
68
|
|
|
@@ -78,9 +78,9 @@ interface PageMeta {
|
|
|
78
78
|
|
|
79
79
|
**`keepalive`**
|
|
80
80
|
|
|
81
|
-
- **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components
|
|
81
|
+
- **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)
|
|
82
82
|
|
|
83
|
-
Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components
|
|
83
|
+
Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive) for a fine-grained control.
|
|
84
84
|
|
|
85
85
|
**`key`**
|
|
86
86
|
|
|
@@ -96,19 +96,19 @@ interface PageMeta {
|
|
|
96
96
|
|
|
97
97
|
**`layoutTransition`**
|
|
98
98
|
|
|
99
|
-
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components
|
|
99
|
+
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
|
|
100
100
|
|
|
101
101
|
Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition.
|
|
102
102
|
|
|
103
103
|
**`middleware`**
|
|
104
104
|
|
|
105
|
-
- **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/
|
|
105
|
+
- **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/navigationguard) | `Array<MiddlewareKey | NavigationGuard>`
|
|
106
106
|
|
|
107
107
|
Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/4.x/guide/directory-structure/app/middleware).
|
|
108
108
|
|
|
109
109
|
**`pageTransition`**
|
|
110
110
|
|
|
111
|
-
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components
|
|
111
|
+
- **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
|
|
112
112
|
|
|
113
113
|
Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition.
|
|
114
114
|
|
|
@@ -122,7 +122,7 @@ interface PageMeta {
|
|
|
122
122
|
|
|
123
123
|
**`redirect`**
|
|
124
124
|
|
|
125
|
-
- **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias
|
|
125
|
+
- **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias)
|
|
126
126
|
|
|
127
127
|
Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location.
|
|
128
128
|
|
|
@@ -215,7 +215,7 @@ definePageMeta({
|
|
|
215
215
|
</script>
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax
|
|
218
|
+
For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax).
|
|
219
219
|
|
|
220
220
|
### Defining Layout
|
|
221
221
|
|
|
@@ -17,7 +17,7 @@ Make sure to always use `await` or `return` on result of `navigateTo` when calli
|
|
|
17
17
|
::
|
|
18
18
|
|
|
19
19
|
::note
|
|
20
|
-
`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.dev/utils/response#
|
|
20
|
+
`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.dev/utils/response#redirectlocation-status-statustext) instead.
|
|
21
21
|
::
|
|
22
22
|
|
|
23
23
|
### Within a Vue Component
|
|
@@ -119,7 +119,7 @@ await navigateTo('https://nuxt.com', {
|
|
|
119
119
|
```ts [Signature]
|
|
120
120
|
export function navigateTo (
|
|
121
121
|
to: RouteLocationRaw | undefined | null,
|
|
122
|
-
options?: NavigateToOptions
|
|
122
|
+
options?: NavigateToOptions,
|
|
123
123
|
): Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw
|
|
124
124
|
|
|
125
125
|
interface NavigateToOptions {
|
|
@@ -148,7 +148,7 @@ type OpenWindowFeatures = {
|
|
|
148
148
|
|
|
149
149
|
### `to`
|
|
150
150
|
|
|
151
|
-
**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/interfaces/
|
|
151
|
+
**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/interfaces/routelocationoptions) | `undefined` | `null`
|
|
152
152
|
|
|
153
153
|
**Default**: `'/'`
|
|
154
154
|
|
|
@@ -186,9 +186,9 @@ An object accepting the following properties:
|
|
|
186
186
|
- **Type**: `number`
|
|
187
187
|
- **Default**: `302`
|
|
188
188
|
|
|
189
|
-
- `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirection takes place on the server side.
|
|
189
|
+
- `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302) by default when the redirection takes place on the server side.
|
|
190
190
|
|
|
191
|
-
This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permanent redirections.
|
|
191
|
+
This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301) can be used for permanent redirections.
|
|
192
192
|
|
|
193
193
|
- `external`
|
|
194
194
|
|
|
@@ -8,4 +8,4 @@ links:
|
|
|
8
8
|
size: xs
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/
|
|
11
|
+
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/onbeforerouteleave" title="Vue Router Docs" target="_blank"}
|
|
@@ -8,4 +8,4 @@ links:
|
|
|
8
8
|
size: xs
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/
|
|
11
|
+
:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/onbeforerouteupdate" title="Vue Router Docs" target="_blank"}
|
|
@@ -36,7 +36,7 @@ const loggedIn = computed(() => !!tokenCookie.value)
|
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
::note{to="/docs/4.x/guide/going-further/experimental-features#cookiestore"}
|
|
39
|
-
|
|
39
|
+
Since [Nuxt v3.12.0](https://github.com/nuxt/nuxt/releases/tag/v3.12.0), the experimental `cookieStore` option is enabled by default. It automatically refreshes the `useCookie` value when cookies change in the browser.
|
|
40
40
|
::
|
|
41
41
|
|
|
42
42
|
## Type
|
|
@@ -9,7 +9,7 @@ links:
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
::note
|
|
12
|
-
Updates the [`app.config`](/docs/4.x/guide/directory-structure/app-config) using deep assignment. Existing (nested) properties will be preserved.
|
|
12
|
+
Updates the [`app.config`](/docs/4.x/guide/directory-structure/app/app-config) using deep assignment. Existing (nested) properties will be preserved.
|
|
13
13
|
::
|
|
14
14
|
|
|
15
15
|
## Usage
|
|
@@ -25,4 +25,4 @@ updateAppConfig(newAppConfig)
|
|
|
25
25
|
console.log(appConfig) // { foo: 'baz' }
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
:read-more{to="/docs/4.x/guide/directory-structure/app-config"}
|
|
28
|
+
:read-more{to="/docs/4.x/guide/directory-structure/app/app-config"}
|