@nuxt/docs 3.20.1 → 3.21.0

package/1.getting-started/09.transitions.md

@@ -5,12 +5,12 @@ navigation.icon: i-lucide-toggle-right
 ---
 
 ::note
-Nuxt leverages Vue's [`<Transition>`](https://vuejs.org/guide/built-ins/transition.html#the-transition-component) component to apply transitions between pages and layouts.
+Nuxt leverages Vue's [`<Transition>`](https://vuejs.org/guide/built-ins/transition#the-transition-component) component to apply transitions between pages and layouts.
 ::
 
 ## Page Transitions
 
-You can enable page transitions to apply an automatic transition for all your [pages](/docs/3.x/guide/directory-structure/pages).
+You can enable page transitions to apply an automatic transition for all your [pages](/docs/3.x/directory-structure/pages).
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -24,7 +24,7 @@ export default defineNuxtConfig({
 If you are changing layouts as well as page, the page transition you set here will not run. Instead, you should set a [layout transition](/docs/3.x/getting-started/transitions#layout-transitions).
 ::
 
-To start adding transition between your pages, add the following CSS to your [`app.vue`](/docs/3.x/guide/directory-structure/app):
+To start adding transition between your pages, add the following CSS to your [`app.vue`](/docs/3.x/directory-structure/app):
 
 ::code-group
 
@@ -115,7 +115,7 @@ Moving to the about page will add the 3d rotation effect:
 
 ## Layout Transitions
 
-You can enable layout transitions to apply an automatic transition for all your [layouts](/docs/3.x/guide/directory-structure/layouts).
+You can enable layout transitions to apply an automatic transition for all your [layouts](/docs/3.x/directory-structure/layouts).
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -125,7 +125,7 @@ export default defineNuxtConfig({
 })
 ```
 
-To start adding transition between your pages and layouts, add the following CSS to your [`app.vue`](/docs/3.x/guide/directory-structure/app):
+To start adding transition between your pages and layouts, add the following CSS to your [`app.vue`](/docs/3.x/directory-structure/app):
 
 ::code-group
 
@@ -229,7 +229,7 @@ definePageMeta({
 
 You can customize these default transition names globally using `nuxt.config`.
 
-Both `pageTransition` and `layoutTransition` keys accept [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition) as JSON serializable values where you can pass the `name`, `mode` and other valid transition-props of the custom CSS transition.
+Both `pageTransition` and `layoutTransition` keys accept [`TransitionProps`](https://vuejs.org/api/built-in-components#transition) as JSON serializable values where you can pass the `name`, `mode` and other valid transition-props of the custom CSS transition.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -310,12 +310,12 @@ definePageMeta({
 ```
 
 ::tip
-Learn more about additional [JavaScript hooks](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) available in the `Transition` component.
+Learn more about additional [JavaScript hooks](https://vuejs.org/guide/built-ins/transition#javascript-hooks) available in the `Transition` component.
 ::
 
 ## Dynamic Transitions
 
-To apply dynamic transitions using conditional logic, you can leverage inline [middleware](/docs/3.x/guide/directory-structure/middleware) to assign a different transition name to `to.meta.pageTransition`.
+To apply dynamic transitions using conditional logic, you can leverage inline [middleware](/docs/3.x/directory-structure/middleware) to assign a different transition name to `to.meta.pageTransition`.
 
 ::code-group
 
@@ -416,11 +416,11 @@ Remember, this page transition cannot be overridden with `definePageMeta` on ind
 
 ## View Transitions API (experimental)
 
-Nuxt ships with an experimental implementation of the [**View Transitions API**](https://developer.chrome.com/docs/web-platform/view-transitions) (see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)). This is an exciting new way to implement native browser transitions which (among other things) have the ability to transition between unrelated elements on different pages.
+Nuxt ships with an experimental implementation of the [**View Transitions API**](https://developer.chrome.com/docs/web-platform/view-transitions) (see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)). This is an exciting new way to implement native browser transitions which (among other things) have the ability to transition between unrelated elements on different pages.
 
-You can check a demo on https://nuxt-view-transitions.surge.sh and the [source on StackBlitz](https://stackblitz.com/edit/nuxt-view-transitions).
+You can check a demo [on StackBlitz](https://stackblitz.com/edit/nuxt-view-transitions).
 
-The Nuxt integration is under active development, but can be enabled with the `experimental.viewTransition` option in your configuration file:
+The Nuxt integration can be enabled with the `experimental.viewTransition` option in your configuration file:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -434,7 +434,7 @@ The possible values are: `false`, `true`, or `'always'`.
 
 If set to true, Nuxt will not apply transitions if the user's browser matches `prefers-reduced-motion: reduce` (recommended). If set to `always`, Nuxt will always apply the transition and it is up to you to respect the user's preference.
 
-By default, view transitions are enabled for all [pages](/docs/3.x/guide/directory-structure/pages), but you can set a different global default.
+By default, view transitions are enabled for all [pages](/docs/3.x/directory-structure/pages), but you can set a different global default.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({

package/1.getting-started/10.data-fetching.md

@@ -80,11 +80,11 @@ async function addTodo () {
 ```
 
 ::warning
-Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](#the-need-for-usefetch-and-useasyncdata). :br
-It is recommended to use `$fetch` for client-side interactions (event-based) or combined with [`useAsyncData`](#useasyncdata) when fetching the initial component data.
+Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](/docs/3.x/getting-started/data-fetching#the-need-for-usefetch-and-useasyncdata). :br
+It is recommended to use `$fetch` for client-side interactions (event-based) or combined with [`useAsyncData`](/docs/3.x/getting-started/data-fetching#useasyncdata) when fetching the initial component data.
 ::
 
-::read-more{to="/docs/api/utils/dollarfetch"}
+::read-more{to="/docs/3.x/api/utils/dollarfetch"}
 Read more about `$fetch`.
 ::
 
@@ -146,9 +146,9 @@ This composable is a wrapper around the [`useAsyncData`](/docs/3.x/api/composabl
 
 :video-accordion{title="Watch a video from Alexander Lichter to avoid using useFetch the wrong way" videoId="njsGVmcWviY"}
 
-:read-more{to="/docs/api/composables/use-fetch"}
+:read-more{to="/docs/3.x/api/composables/use-fetch"}
 
-:link-example{to="/docs/examples/features/data-fetching"}
+:link-example{to="/docs/3.x/examples/features/data-fetching"}
 
 ## `useAsyncData`
 
@@ -220,7 +220,7 @@ await useAsyncData(() => offersStore.getOffer(route.params.slug))
 ```
 ::
 
-::read-more{to="/docs/api/composables/use-async-data"}
+::read-more{to="/docs/3.x/api/composables/use-async-data"}
 Read more about `useAsyncData`.
 ::
 
@@ -280,11 +280,11 @@ const { status, data: posts } = useLazyFetch('/api/posts')
 </script>
 ```
 
-::read-more{to="/docs/api/composables/use-lazy-fetch"}
+::read-more{to="/docs/3.x/api/composables/use-lazy-fetch"}
 Read more about `useLazyFetch`.
 ::
 
-::read-more{to="/docs/api/composables/use-lazy-async-data"}
+::read-more{to="/docs/3.x/api/composables/use-lazy-async-data"}
 Read more about `useLazyAsyncData`.
 ::
 
@@ -307,7 +307,7 @@ const { status, data: comments } = useFetch('/api/comments', {
 })
 ```
 
-The `useFetch` composable is meant to be invoked in setup method or called directly at the top level of a function in lifecycle hooks, otherwise you should use [`$fetch` method](#fetch).
+The `useFetch` composable is meant to be invoked in setup method or called directly at the top level of a function in lifecycle hooks, otherwise you should use [`$fetch` method](/docs/3.x/getting-started/data-fetching#fetch).
 
 ### Minimize payload size
 
@@ -433,7 +433,7 @@ const { data, error, execute, refresh } = await useFetch('/api/users')
 </template>
 ```
 
-The `execute` function is an alias for `refresh` that works in exactly the same way but is more semantic for cases when the fetch is [not immediate](#not-immediate).
+The `execute` function is an alias for `refresh` that works in exactly the same way but is more semantic for cases when the fetch is [not immediate](/docs/3.x/getting-started/data-fetching#not-immediate).
 
 ::tip
 To globally refetch or invalidate cached data, see [`clearNuxtData`](/docs/3.x/api/utils/clear-nuxt-data) and [`refreshNuxtData`](/docs/3.x/api/utils/refresh-nuxt-data).
@@ -483,7 +483,7 @@ const { data, error, refresh } = await useFetch(`/api/users/${id.value}`, {
 </script>
 ```
 
-If you need to change the URL based on a reactive value, you may want to use a [computed URL](#computed-url) instead.
+If you need to change the URL based on a reactive value, you may want to use a [computed URL](/docs/3.x/getting-started/data-fetching#computed-url) instead.
 
 When reactive fetch options are provided, they'll be automatically watched and trigger refetches. In some cases, it can be useful to opt-out of this behavior by specifying `watch: false`.
 
@@ -516,9 +516,9 @@ const { data, status } = useLazyFetch('/api/user', {
 </script>
 ```
 
-In the case of more complex URL construction, you may use a callback as a [computed getter](https://vuejs.org/guide/essentials/computed.html) that returns the URL string.
+In the case of more complex URL construction, you may use a callback as a [computed getter](https://vuejs.org/guide/essentials/computed) that returns the URL string.
 
-Every time a dependency changes, the data will be fetched using the newly constructed URL. Combine this with [not-immediate](#not-immediate), and you can wait until the reactive element changes before fetching.
+Every time a dependency changes, the data will be fetched using the newly constructed URL. Combine this with [not-immediate](/docs/3.x/getting-started/data-fetching#not-immediate), and you can wait until the reactive element changes before fetching.
 
 ```vue
 <script setup lang="ts">
@@ -555,7 +555,7 @@ const pending = computed(() => status.value === 'pending')
 </template>
 ```
 
-If you need to force a refresh when other reactive values change, you can also [watch other values](#watch).
+If you need to force a refresh when other reactive values change, you can also [watch other values](/docs/3.x/getting-started/data-fetching#watch).
 
 ### Not immediate
 
@@ -657,11 +657,11 @@ export default defineNuxtComponent({
 Using `<script setup>` or `<script setup lang="ts">` are the recommended way of declaring Vue components in Nuxt.
 ::
 
-:read-more{to="/docs/api/utils/define-nuxt-component"}
+:read-more{to="/docs/3.x/api/utils/define-nuxt-component"}
 
 ## Serializing Data From Server to Client
 
-When using `useAsyncData` and `useLazyAsyncData` to transfer data fetched on server to the client (as well as anything else that utilizes [the Nuxt payload](/docs/3.x/api/composables/use-nuxt-app#payload)), the payload is serialized with [`devalue`](https://github.com/Rich-Harris/devalue). This allows us to transfer not just basic JSON but also to serialize and revive/deserialize more advanced kinds of data, such as regular expressions, Dates, Map and Set, `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError` - and more.
+When using `useAsyncData` and `useLazyAsyncData` to transfer data fetched on server to the client (as well as anything else that utilizes [the Nuxt payload](/docs/3.x/api/composables/use-nuxt-app#payload)), the payload is serialized with [`devalue`](https://github.com/sveltejs/devalue). This allows us to transfer not just basic JSON but also to serialize and revive/deserialize more advanced kinds of data, such as regular expressions, Dates, Map and Set, `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError` - and more.
 
 It is also possible to define your own serializer/deserializer for types that are not supported by Nuxt. You can read more in the [`useNuxtApp`](/docs/3.x/api/composables/use-nuxt-app#payload) docs.
 
@@ -733,7 +733,7 @@ const { data } = await useFetch('/api/bar')
 
 Nuxt does not currently support an alternative serializer to `JSON.stringify`. However, you can return your payload as a normal string and utilize the `toJSON` method to maintain type safety.
 
-In the example below, we use [superjson](https://github.com/blitz-js/superjson) as our serializer.
+In the example below, we use [superjson](https://github.com/flightcontrolhq/superjson) as our serializer.
 
 ```ts [server/api/superjson.ts]
 import superjson from 'superjson'
@@ -771,7 +771,7 @@ const { data } = await useFetch('/api/superjson', {
 ### Consuming SSE (Server-Sent Events) via POST request
 
 ::tip
-If you're consuming SSE via GET request, you can use [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or VueUse composable [`useEventSource`](https://vueuse.org/core/useEventSource/).
+If you're consuming SSE via GET request, you can use [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or VueUse composable [`useEventSource`](https://vueuse.org/core/useeventsource/).
 ::
 
 When consuming SSE via POST request, you need to handle the connection manually. Here's how you can do it:

package/1.getting-started/11.state-management.md

@@ -6,7 +6,7 @@ navigation.icon: i-lucide-database
 
 Nuxt provides the [`useState`](/docs/3.x/api/composables/use-state) composable to create a reactive and SSR-friendly shared state across components.
 
-[`useState`](/docs/3.x/api/composables/use-state) is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core.html#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
+[`useState`](/docs/3.x/api/composables/use-state) is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
 
 :video-accordion{title="Watch a video from Alexander Lichter about why and when to use useState" videoId="mv0WcBABcIk"}
 
@@ -14,7 +14,7 @@ Nuxt provides the [`useState`](/docs/3.x/api/composables/use-state) composable t
 Because the data inside [`useState`](/docs/3.x/api/composables/use-state) will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.
 ::
 
-::read-more{to="/docs/api/composables/use-state"}
+::read-more{to="/docs/3.x/api/composables/use-state"}
 Read more about `useState` composable.
 ::
 
@@ -53,7 +53,7 @@ const counter = useState('counter', () => Math.round(Math.random() * 1000))
 </template>
 ```
 
-:link-example{to="/docs/examples/features/state-management"}
+:link-example{to="/docs/3.x/examples/features/state-management"}
 
 ::note
 To globally invalidate cached state, see [`clearNuxtState`](/docs/3.x/api/utils/clear-nuxt-state) util.
@@ -61,7 +61,7 @@ To globally invalidate cached state, see [`clearNuxtState`](/docs/3.x/api/utils/
 
 ### Initializing State
 
-Most of the time, you will want to initialize your state with data that resolves asynchronously. You can use the [`app.vue`](/docs/3.x/guide/directory-structure/app) component with the [`callOnce`](/docs/3.x/api/utils/call-once) util to do so.
+Most of the time, you will want to initialize your state with data that resolves asynchronously. You can use the [`app.vue`](/docs/3.x/directory-structure/app) component with the [`callOnce`](/docs/3.x/api/utils/call-once) util to do so.
 
 ```vue twoslash [app.vue]
 <script setup lang="ts">
@@ -77,7 +77,7 @@ await callOnce(async () => {
 This is similar to the [`nuxtServerInit` action](https://v2.nuxt.com/docs/directory-structure/store/#the-nuxtserverinit-action) in Nuxt 2, which allows filling the initial state of your store server-side before rendering the page.
 ::
 
-:read-more{to="/docs/api/utils/call-once"}
+:read-more{to="/docs/3.x/api/utils/call-once"}
 
 ### Usage with Pinia
 
@@ -194,11 +194,11 @@ const date = useLocaleDate(new Date('2016-10-26'))
 ```
 ::
 
-:link-example{to="/docs/examples/advanced/locale"}
+:link-example{to="/docs/3.x/examples/advanced/locale"}
 
 ## Shared State
 
-By using [auto-imported composables](/docs/3.x/guide/directory-structure/composables) we can define global type-safe states and import them across the app.
+By using [auto-imported composables](/docs/3.x/directory-structure/composables) we can define global type-safe states and import them across the app.
 
 ```ts twoslash [composables/states.ts]
 export const useColor = () => useState<string>('color', () => 'pink')

package/1.getting-started/12.error-handling.md

@@ -8,7 +8,7 @@ Nuxt is a full-stack framework, which means there are several sources of unpreve
 
 - Errors during the Vue rendering lifecycle (SSR & CSR)
 - Server and client startup errors (SSR + CSR)
-- Errors during Nitro server lifecycle ([`server/`](/docs/3.x/guide/directory-structure/server) directory)
+- Errors during Nitro server lifecycle ([`server/`](/docs/3.x/directory-structure/server) directory)
 - Errors downloading JS chunks
 
 ::tip
@@ -17,11 +17,11 @@ Nuxt is a full-stack framework, which means there are several sources of unpreve
 
 ## Vue Errors
 
-You can hook into Vue errors using [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
+You can hook into Vue errors using [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured).
 
 In addition, Nuxt provides a [`vue:error`](/docs/3.x/api/advanced/hooks#app-hooks-runtime) hook that will be called if any errors propagate up to the top level.
 
-If you are using an error reporting framework, you can provide a global handler through [`vueApp.config.errorHandler`](https://vuejs.org/api/application.html#app-config-errorhandler). It will receive all Vue errors, even if they are handled.
+If you are using an error reporting framework, you can provide a global handler through [`vueApp.config.errorHandler`](https://vuejs.org/api/application#app-config-errorhandler). It will receive all Vue errors, even if they are handled.
 
 ```ts twoslash [plugins/error-handler.ts]
 export default defineNuxtPlugin((nuxtApp) => {
@@ -37,7 +37,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 ```
 
 ::note
-Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) lifecycle hook.
+Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured) lifecycle hook.
 ::
 
 ## Startup Errors
@@ -45,7 +45,7 @@ Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org
 Nuxt will call the `app:error` hook if there are any errors in starting your Nuxt application.
 
 This includes:
-- running [Nuxt plugins](/docs/3.x/guide/directory-structure/plugins)
+- running [Nuxt plugins](/docs/3.x/directory-structure/plugins)
 - processing `app:created` and `app:beforeMount` hooks
 - rendering your Vue app to HTML (during SSR)
 - mounting the app (on client-side), though you should handle this case with `onErrorCaptured` or with `vue:error`
@@ -53,7 +53,7 @@ This includes:
 
 ## Nitro Server Errors
 
-You cannot currently define a server-side handler for these errors, but can render an error page, see the [Render an Error Page](#error-page) section.
+You cannot currently define a server-side handler for these errors, but can render an error page, see the [Render an Error Page](/docs/3.x/getting-started/error-handling#error-page) section.
 
 ## Errors with JS Chunks
 
@@ -78,7 +78,7 @@ It can also occur on the client side when:
 - mounting your app if the error was not handled with `onErrorCaptured` or `vue:error` hook
 - the Vue app is initialized and mounted in browser (`app:mounted`).
 
-::read-more{to="/docs/api/advanced/hooks"}
+::read-more{to="/docs/3.x/api/advanced/hooks"}
 Discover all the Nuxt lifecycle hooks.
 ::
 
@@ -99,7 +99,7 @@ const handleError = () => clearError({ redirect: '/' })
 
 <template>
   <div>
-    <h2>{{ error?.statusCode }}</h2>
+    <h2>{{ error?.status }}</h2>
     <button @click="handleError">
       Clear errors
     </button>
@@ -107,7 +107,7 @@ const handleError = () => clearError({ redirect: '/' })
 </template>
 ```
 
-::read-more{to="/docs/guide/directory-structure/error"}
+::read-more{to="/docs/3.x/directory-structure/error"}
 Read more about `error.vue` and its uses.
 ::
 
@@ -128,7 +128,7 @@ Make sure to check before using anything dependent on Nuxt plugins, such as `$ro
 ::
 
 ::note
-Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](#useerror) in middleware to check if an error is being handled.
+Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/3.x/getting-started/error-handling#useerror) in middleware to check if an error is being handled.
 ::
 
 ::note
@@ -140,25 +140,25 @@ If you are running on Node 16 and you set any cookies when rendering your error
 ### `useError`
 
 ```ts [TS Signature]
-function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>
+function useError (): Ref<Error | { url, status, statusText, message, description, data }>
 ```
 
 This function will return the global Nuxt error that is being handled.
 
-::read-more{to="/docs/api/composables/use-error"}
+::read-more{to="/docs/3.x/api/composables/use-error"}
 Read more about `useError` composable.
 ::
 
 ### `createError`
 
 ```ts [TS Signature]
-function createError (err: string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error
+function createError (err: string | { cause, data, message, name, stack, status, statusText, fatal }): Error
 ```
 
 Create an error object with additional metadata. You can pass a string to be set as the error `message` or an object containing error properties. It is usable in both the Vue and Server portions of your app, and is meant to be thrown.
 
 If you throw an error created with `createError`:
-- on server-side, it will trigger a full-screen error page which you can clear with [`clearError`](#clearerror).
+- on server-side, it will trigger a full-screen error page which you can clear with [`clearError`](/docs/3.x/getting-started/error-handling#clearerror).
 - on client-side, it will throw a non-fatal error for you to handle. If you need to trigger a full-screen error page, then you can do this by setting `fatal: true`.
 
 ```vue twoslash [pages/movies/[slug\\].vue]
@@ -168,28 +168,34 @@ const { data } = await useFetch(`/api/movies/${route.params.slug}`)
 
 if (!data.value) {
   throw createError({
-    statusCode: 404,
-    statusMessage: 'Page Not Found',
+    status: 404,
+    statusText: 'Page Not Found',
   })
 }
 </script>
 ```
 
-::read-more{to="/docs/api/utils/create-error"}
+::tip
+The `statusText` property is intended for short, HTTP-compliant status texts (e.g., "Not Found"). It should only contain horizontal tabs, spaces, and visible ASCII characters (`[\t\u0020-\u007E]`).
+
+For any detailed descriptions, multi-line messages, or content with non-ASCII characters, you should always use the `message` property instead.
+::
+
+::read-more{to="/docs/3.x/api/utils/create-error"}
 Read more about `createError` util.
 ::
 
 ### `showError`
 
 ```ts [TS Signature]
-function showError (err: string | Error | { statusCode, statusMessage }): Error
+function showError (err: string | Error | { status, statusText }): Error
 ```
 
-You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or `setup()` functions. It will trigger a full-screen error page which you can clear with [`clearError`](#clearerror).
+You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or `setup()` functions. It will trigger a full-screen error page which you can clear with [`clearError`](/docs/3.x/getting-started/error-handling#clearerror).
 
 It is recommended instead to use `throw createError()`.
 
-::read-more{to="/docs/api/utils/show-error"}
+::read-more{to="/docs/3.x/api/utils/show-error"}
 Read more about `showError` util.
 ::
 
@@ -201,7 +207,7 @@ function clearError (options?: { redirect?: string }): Promise<void>
 
 This function will clear the currently handled Nuxt error. It also takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).
 
-::read-more{to="/docs/api/utils/clear-error"}
+::read-more{to="/docs/3.x/api/utils/clear-error"}
 Read more about `clearError` util.
 ::
 
@@ -232,4 +238,4 @@ If you navigate to another route, the error will be cleared automatically.
 </template>
 ```
 
-:link-example{to="/docs/examples/advanced/error-handling"}
+:link-example{to="/docs/3.x/examples/advanced/error-handling"}

package/1.getting-started/13.server.md

@@ -4,7 +4,7 @@ description: Build full-stack applications with Nuxt's server framework. You can
 navigation.icon: i-lucide-pc-case
 ---
 
-:read-more{to="/docs/guide/directory-structure/server"}
+:read-more{to="/docs/3.x/directory-structure/server"}
 
 ## Powered by Nitro
 
@@ -38,7 +38,7 @@ And you can directly return `text`, `json`, `html` or even a `stream`.
 
 Out-of-the-box, it supports **hot module replacement** and **auto-import** like the other parts of your Nuxt application.
 
-:read-more{to="/docs/guide/directory-structure/server"}
+:read-more{to="/docs/3.x/directory-structure/server"}
 
 ## Universal Deployment
 
@@ -49,17 +49,17 @@ Nitro offers the ability to deploy your Nuxt app anywhere, from a bare metal ser
 There are more than 15 presets to build your Nuxt app for different cloud providers and servers, including:
 
 - [Cloudflare Workers](https://workers.cloudflare.com)
-- [Netlify Functions](https://www.netlify.com/products/functions)
-- [Vercel Edge Network](https://vercel.com/docs/edge-network)
+- [Netlify Functions](https://www.netlify.com/platform/core/functions/)
+- [Vercel Cloud](https://vercel.com/home)
 
 Or for other runtimes:
 
 ::card-group
-  :card{icon="i-logos-deno" title="Deno" to="https://deno.land" target="_blank"}
-  :card{icon="i-logos-bun" title="Bun" to="https://bun.sh" target="_blank"}
+  :card{icon="i-logos-deno" title="Deno" to="https://deno.com" target="_blank"}
+  :card{icon="i-logos-bun" title="Bun" to="https://bun.com" target="_blank"}
 ::
 
-:read-more{to="/docs/getting-started/deployment"}
+:read-more{to="/docs/3.x/getting-started/deployment"}
 
 ## Hybrid Rendering
 
@@ -81,7 +81,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="/docs/guide/concepts/rendering#hybrid-rendering"}
+::read-more{to="/docs/3.x/guide/concepts/rendering#hybrid-rendering"}
 Learn about all available route rules are available to customize the rendering mode of your routes.
 ::
 
@@ -91,4 +91,4 @@ Some route rules (`appMiddleware`, `redirect` and `prerender`) also affect clien
 
 Nitro is used to build the app for server side rendering, as well as pre-rendering.
 
-:read-more{to="/docs/guide/concepts/rendering"}
+:read-more{to="/docs/3.x/guide/concepts/rendering"}

package/1.getting-started/14.layers.md

@@ -9,8 +9,8 @@ One of the core features of Nuxt is the layers and extending support. You can ex
 ## Use Cases
 
 - Share reusable configuration presets across projects using `nuxt.config` and `app.config`
-- Create a component library using [`components/`](/docs/3.x/guide/directory-structure/components) directory
-- Create utility and composable library using [`composables/`](/docs/3.x/guide/directory-structure/composables) and [`utils/`](/docs/3.x/guide/directory-structure/utils) directories
+- Create a component library using [`components/`](/docs/3.x/directory-structure/components) directory
+- Create utility and composable library using [`composables/`](/docs/3.x/directory-structure/composables) and [`utils/`](/docs/3.x/directory-structure/utils) directories
 - Create Nuxt module presets
 - Share standard setup across projects
 - Create Nuxt themes
@@ -30,7 +30,7 @@ In addition, named layer aliases to the `srcDir` of each of these layers will au
 Named layer aliases were introduced in Nuxt v3.16.0.
 ::
 
-In addition, you can extend from a layer by adding the [extends](/docs/3.x/api/nuxt-config#extends) property to your [`nuxt.config`](/docs/3.x/guide/directory-structure/nuxt-config) file.
+In addition, you can extend from a layer by adding the [extends](/docs/3.x/api/nuxt-config#extends) property to your [`nuxt.config`](/docs/3.x/directory-structure/nuxt-config) file.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -56,6 +56,10 @@ export default defineNuxtConfig({
 })
 ```
 
+::note
+If a branch is not specified, this will clone `main`.
+::
+
 ::tip
 You can override a layer's alias by specifying it in the options next to the layer source.
 
@@ -76,38 +80,66 @@ export default defineNuxtConfig({
 
 ::
 
-Nuxt uses [unjs/c12](https://c12.unjs.io) and [unjs/giget](https://giget.unjs.io) for extending remote layers. Check the documentation for more information and all available options.
+Nuxt uses [unjs/c12](https://github.com/unjs/c12) and [unjs/giget](https://github.com/unjs/giget) for extending remote layers. Check the documentation for more information and all available options.
 
 ## Layer Priority
 
 When using multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.
 
-The priority order from highest to lowest is:
+### Priority Order
+
+From highest to lowest priority:
 
 1. **Your project files** - always have the highest priority
 2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
 3. **Layers in `extends`** config - first entry has higher priority than second
 
-### When to Use Each
+### Practical Example
 
-- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
-- **`~~/layers` directory** - Use for local layers that are part of your project
+Consider multiple layers defining the same component:
+
+```bash [Directory structure]
+layers/
+  1.base/
+    components/Button.vue    # Base button style
+  2.theme/
+    components/Button.vue    # Themed button (overrides base)
+app/
+  components/Button.vue          # Project button (overrides all layers)
+```
+
+In this case:
+- If only layers exist, `2.theme/Button.vue` is used (higher alphabetically)
+- If `components/Button.vue` exists in your project, it overrides all layers
+
+### Controlling Priority
+
+You can prefix layer directories with numbers to control the order:
+
+```bash [Directory structure]
+layers/
+  1.base/        # Lowest priority
+  2.features/    # Medium priority
+  3.admin/       # Highest priority (among layers)
+```
 
 ::tip
-If you need to control the order of auto-scanned layers, you can prefix them with numbers: `~/layers/1.z-layer`, `~/layers/2.a-layer`. This way `2.a-layer` will have higher priority than `1.z-layer`.
+This pattern is useful for creating base layers with defaults that can be progressively overridden by more specific layers.
 ::
 
-### Example
+### When to Use Each
+
+- **`~~/layers` directory** - Use for local layers that are part of your project
+- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
+
+### Full Example with extends
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   extends: [
-    // Local layer outside the project
-    '../base',
-    // NPM package
-    '@my-themes/awesome',
-    // Remote repository
-    'github:my-themes/awesome#v1',
+    '../base', // Local layer outside project
+    '@my-themes/awesome', // NPM package
+    'github:my-themes/awesome#v1', // Remote repository
   ],
 })
 ```
@@ -119,9 +151,11 @@ If you also have `~~/layers/custom`, the priority order is:
 - `@my-themes/awesome`
 - `github:my-themes/awesome#v1` (lowest)
 
-This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
+::read-more{to="/docs/3.x/directory-structure/layers"}
+Learn about the **layers/ directory** to organize and share reusable code, components, composables, and configurations across your Nuxt application.
+::
 
-::read-more{to="/docs/guide/going-further/layers"}
+::read-more{to="/docs/3.x/guide/going-further/layers"}
 Read more about layers in the **Layer Author Guide**.
 ::