Merge remote-tracking branch 'origin/main' into fix/update-vitest-import

docs/content/1.getting-started/10.deployment.md

@@ -137,15 +137,15 @@ NITRO_PRESET=node-server nuxt build
 
 Nuxt 3 can be deployed to several cloud providers with a minimal amount of configuration:
 
-- :IconCloud{class="h-5 w-4 inline mb-2"} [AWS](https://nitro.unjs.io/deploy/providers/aws)
-- :LogoAzure{class="h-5 w-4 inline mb-2"} [Azure](https://nitro.unjs.io/deploy/providers/azure)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [Cleavr](https://nitro.unjs.io/deploy/providers/cleavr)
-- :LogoCloudFlare{class="h-5 w-4 inline mb-2"} [CloudFlare](https://nitro.unjs.io/deploy/providers/cloudflare)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [Digital Ocean](https://nitro.unjs.io/deploy/providers/digitalocean)
-- :LogoFirebase{class="h-5 w-4 inline mb-2"} [Firebase](https://nitro.unjs.io/deploy/providers/firebase)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [heroku](https://nitro.unjs.io/deploy/providers/heroku)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [layer0](https://nitro.unjs.io/deploy/providers/layer0)
-- :LogoNetlify{class="h-5 w-4 inline mb-2"} [Netlify](https://nitro.unjs.io/deploy/providers/netlify)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [Render](https://nitro.unjs.io/deploy/providers/render)
-- :IconCloud{class="h-5 w-4 inline mb-2"} [Stormkit](https://nitro.unjs.io/deploy/providers/stormkit)
-- :LogoVercel{class="h-5 w-4 inline mb-2"} [Vercel](https://nitro.unjs.io/deploy/providers/vercel)
+- :icon{name="logos:aws" class="h-5 w-4 inline mb-2"} [AWS](https://nitro.unjs.io/deploy/providers/aws)
+- :icon{name="logos:microsoft-azure" class="h-5 w-4 inline mb-2"} [Azure](https://nitro.unjs.io/deploy/providers/azure)
+- :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Cleavr](https://nitro.unjs.io/deploy/providers/cleavr)
+- :icon{name="logos:cloudflare" class="h-5 w-4 inline mb-2"} [CloudFlare](https://nitro.unjs.io/deploy/providers/cloudflare)
+- :icon{name="logos:digital-ocean" class="h-5 w-4 inline mb-2"} [Digital Ocean](https://nitro.unjs.io/deploy/providers/digitalocean)
+- :icon{name="logos:firebase" class="h-5 w-4 inline mb-2"} [Firebase](https://nitro.unjs.io/deploy/providers/firebase)
+- :icon{name="logos:heroku-icon" class="h-5 w-4 inline mb-2"} [heroku](https://nitro.unjs.io/deploy/providers/heroku)
+- :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [layer0](https://nitro.unjs.io/deploy/providers/layer0)
+- :icon{name="logos:netlify" class="h-5 w-4 inline mb-2"} [Netlify](https://nitro.unjs.io/deploy/providers/netlify)
+- :icon{name="simple-icons:render" class="h-5 w-4 inline mb-2"} [Render](https://nitro.unjs.io/deploy/providers/render)
+- :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Stormkit](https://nitro.unjs.io/deploy/providers/stormkit)
+- :icon{name="logos:vercel-icon" class="h-5 w-4 inline mb-2"} [Vercel](https://nitro.unjs.io/deploy/providers/vercel)

docs/content/2.guide/2.directory-structure/1.composables.md

@@ -11,7 +11,7 @@ Nuxt 3 uses the `composables/` directory to automatically import your Vue compos
 
 Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the types.
 
-Be aware that you have to run `nuxi prepare`, `nuxi dev` or `nuxi build` in order to let Nuxt generates the types. If you create a composable without having the dev server running, typescript will throw an error `Cannot find name 'useBar'.`
+Be aware that you have to run `nuxi prepare`, `nuxi dev` or `nuxi build` in order to let Nuxt generate the types. If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`
 
 ## Usage
 

docs/content/2.guide/2.directory-structure/1.utils.md

@@ -0,0 +1,16 @@
+---
+navigation.icon: IconDirectory
+title: 'utils'
+head.title: Utils
+description: Use the utils/ directory to auto-import your utility functions throughout your application.
+---
+
+# Utils Directory
+
+Nuxt 3 uses the `utils/` directory to automatically import helper functions and other utilities throughout your application using [auto-imports](/guide/concepts/auto-imports)!
+
+::alert{type=info}
+The main purpose of the `utils/` directory is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
+
+The way `utils/` auto-imports work and are scanned is identical to [the composables/ directory](/guide/directory-structure/composables). You can see examples and more information about how they work in that section of the docs.
+::

docs/content/3.api/1.composables/use-request-headers.md

@@ -5,7 +5,7 @@ description: "Use useRequestHeaders to access the incoming request headers."
 
 # `useRequestHeaders`
 
-Within your pages, components, and plugins you can use `useRequestHeaders` to access the incoming request headers.
+You can use built-in `useRequestHeaders` composable to access the incoming request headers within your pages, components, and plugins.
 
 ```js
 // Get all request headers
@@ -18,3 +18,21 @@ const headers = useRequestHeaders(['cookie'])
 ::alert{icon=👉}
 In the browser, `useRequestHeaders` will return an empty object.
 ::
+
+## Example
+
+We can use `useRequestHeaders` to access and proxy the initial request's `authorization` header to any future internal requests during SSR.
+
+The example below adds the `authorization` request header to an isomorphic `$fetch` call.
+
+```vue [pages/some-page.vue]
+<script setup>
+const { data } = await useFetch('/api/confidential', {
+  headers: useRequestHeaders(['authorization'])
+})
+</script>
+```
+
+::alert{icon=👉}
+[Another example](/getting-started/data-fetching#example-pass-client-headers-to-the-api) shows how we can pass cookies from the initial request to another API route.
+::

docs/content/3.api/3.utils/refresh-nuxt-data.md

@@ -5,15 +5,67 @@ description: refreshNuxtData refetches all data from the server and updates the
 
 # `refreshNuxtData`
 
-`refreshNuxtData` refetches all data from the server and updates the page.
+`refreshNuxtData` re-fetches all data from the server and updates the page as well as invalidates the cache of `useAsyncData`, `useLazyAsyncData`, `useFetch` and `useLazyFetch`.
 
-::ReadMore{link="/getting-started/data-fetching"}
-::
+## Type
 
 ```ts
 refreshNuxtData(keys?: string | string[])
 ```
 
-Available options:
+**Parameters:**
+
+* `keys`:
+
+    **Type**: `String | String[]`
+
+    `refreshNuxtData` accepts a single or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All `useAsyncData` and `useFetch` are re-fetched when no `keys` are specified.
+
+## Examples
+
+### Refresh All data
+
+This example below refreshes all data being fetched using `useAsyncData` and `useFetch` on the current page.
+
+```vue [pages/some-page.vue]
+<template>
+  <div>
+    <button :disabled="refreshing" @click="refreshAll">
+      Refetch All Data
+    </button>
+  </div>
+</template>
+
+<script setup>
+const refreshing = ref(false)
+const refreshAll = async () => {
+  refreshing.value = true
+  try {
+    await refreshNuxtData()
+  } finally {
+    refreshing.value = false
+  }
+}
+</script>
+```
+
+### Refresh Specific Data
+
+This example below refreshes only data where the key matches to `count`.
+
+```vue [pages/some-page.vue]
+<template>
+  <div>
+    {{ pending ? 'Loading' : count }}
+  </div>
+  <button @click="refresh">Refresh</button>
+</template>
 
-* `keys`: Provides an array of keys that are used in `useAsyncData` to refetch. When it's not specified, all `useAsyncData` and `useFetch` will be refetched.
+<script setup>
+const { pending, data: count } = useLazyAsyncData('count', () => $fetch('/api/count'))
+const refresh = () => refreshNuxtData('count')
+</script>
+```
+
+::ReadMore{link="/getting-started/data-fetching"}
+::

docs/content/3.api/4.advanced/2.kit.md

@@ -56,6 +56,12 @@ description: Nuxt Kit provides composable utilities to help interacting with Nux
 
 - `useNuxt()`
 
+### Pages
+
+[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/pages.ts)
+
+- `extendPages (callback: pages => void)`
+
 ### Plugins
 
 [source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/plugin.ts)

docs/content/4.examples/0.essentials/hello-world.md

@@ -1,9 +1,9 @@
 ---
-title: "Hello World"
-description: "A minimal Nuxt 3 application only requires the `app.vue` and `nuxt.config.js` files."
 toc: false
 ---
 
+# Hello World
+
 A minimal Nuxt 3 application only requires the `app.vue` and `nuxt.config.js` files.
 
 ::ReadMore{link="/getting-started/introduction"}

docs/content/4.examples/1.app/app-config.md

@@ -1,5 +1,5 @@
 ---
-template: Example
+toc: false
 ---
 
 # `app.config`

docs/content/4.examples/1.app/error-handling.md

@@ -1,14 +1,12 @@
 ---
-title: "Error Handling"
-description: "This example shows how to handle errors in different contexts: pages, plugins, components and middleware."
 toc: false
 ---
 
 # Error Handling
 
 This example shows how to handle errors in different contexts: pages, plugins, components and middleware.
 
-::ReadMore{link="/getting-started/error-handling"}
+:ReadMore{link="/getting-started/error-handling"}
 ::
 
 ::sandbox{repo="nuxt/framework" branch="main" dir="examples/app/error-handling" file="app.vue"}

docs/content/4.examples/1.app/plugins.md

@@ -1,10 +1,12 @@
 ---
-title: "Plugins"
-description: "This example shows how to use the plugins/ directory to auto-register plugins."
 toc: false
 ---
 
-::ReadMore{link="/guide/directory-structure/plugins"}
+# Plugins
+
+This example shows how to use the plugins/ directory to auto-register plugins.
+
+:ReadMore{link="/guide/directory-structure/plugins"}
 ::
 
 ::sandbox{repo="nuxt/framework" branch="main" dir="examples/app/plugins" file="app.vue"}

docs/content/4.examples/1.app/teleport.md

@@ -1,9 +1,11 @@
 ---
-title: "Teleport"
-description: "This example shows how to use the <Teleport> with client-side and server-side rendering."
 toc: false
 ---
 
+# Teleport
+
+This example shows how to use the <Teleport> with client-side and server-side rendering.
+
 Vue 3 provides the [`<Teleport>` component](https://vuejs.org/guide/built-ins/teleport.html) which allows content to be rendered elsewhere in the DOM, outside of the Vue application.
 
 This example shows how to use the `<Teleport>` with client-side and server-side rendering.

docs/content/4.examples/2.auto-imports/components.md

@@ -1,10 +1,10 @@
 ---
-title: "Components"
-description: "You can configure other directories to support components auto-imports."
 toc: false
 ---
 
-Components in the `components/` directory are auto-imported and can be used directly in your templates.
+# Components
+
+Components in the `components/` directory are auto-imported and can be used directly in your templates. You can configure other directories to support components auto-imports.
 
 ::ReadMore{link="/guide/directory-structure/components"}
 ::

docs/content/4.examples/2.auto-imports/composables.md

@@ -1,10 +1,12 @@
 ---
-title: "Composables"
-description: "This example shows how to use the composables/ directory to auto-import composables."
 toc: false
 ---
 
-If the component file provides a default export, the name of the composable will be mapped to the name of the file. Named exports can be used as-is.
+# Composables
+
+This example shows how to use the composables/ directory to auto-import composables.
+
+If the composable file provides a default export, the name of the composable will be mapped to the name of the file. Named exports can be used as-is.
 
 ::ReadMore{link="/guide/directory-structure/composables"}
 ::

docs/content/4.examples/3.composables/use-async-data.md

@@ -1,9 +1,11 @@
 ---
-title: "useAsyncData"
-description: "This example shows how to use useAsyncData to fetch data from an API endpoint."
 toc: false
 ---
 
+# useAsyncData
+
+This example shows how to use useAsyncData to fetch data from an API endpoint.
+
 ::alert{type=info icon=💡}
 Nuxt will automatically read files in the `~/server/api` directory to create API endpoints.
 ::

docs/content/4.examples/3.composables/use-cookie.md

@@ -1,9 +1,11 @@
 ---
-title: "useCookie"
-description: "This example shows how to use the useCookie API to persist small amounts of data that both client and server can use."
 toc: false
 ---
 
+# useCookie
+
+This example shows how to use the useCookie API to persist small amounts of data that both client and server can use.
+
 ::ReadMore{link="/api/composables/use-cookie"}
 ::
 

docs/content/4.examples/3.composables/use-fetch.md

@@ -1,9 +1,11 @@
 ---
-title: "useFetch"
-description: "This example shows how to use useFetch to fetch data from an API endpoint."
 toc: false
 ---
 
+# useFetch
+
+This example shows how to use useFetch to fetch data from an API endpoint.
+
 ::alert{type=info icon=💡}
 Nuxt will automatically read files in the `~/server/api` directory to create API endpoints.
 ::

docs/content/4.examples/3.composables/use-head.md

@@ -1,9 +1,11 @@
 ---
 toc: false
-description: "This example shows how to use useHead and Nuxt built-in components to bind meta data to the head of the page."
-title: "useHead"
 ---
 
+# useHead
+
+This example shows how to use useHead and Nuxt built-in components to bind meta data to the head of the page.
+
 ::ReadMore{link="/api/composables/use-head"}
 ::
 

docs/content/4.examples/3.composables/use-state.md

@@ -1,9 +1,11 @@
 ---
-title: "useState"
-description: "useState is an SSR-friendly ref replacement."
 toc: false
 ---
 
+# useState
+
+This example showcase the `useState` composable, an SSR-friendly ref replacement.
+
 Its value will be preserved after server-side rendering and shared across all components using a unique key.
 
 ::alert{type=info icon=👉}

docs/content/4.examples/4.routing/layouts.md

@@ -1,9 +1,11 @@
 ---
-title: "Layouts"
-description: "This example shows how to define default and custom layouts."
 toc: false
 ---
 
+# Layouts
+
+This example shows how to define default and custom layouts.
+
 ::ReadMore{link="/guide/directory-structure/layouts"}
 ::
 

docs/content/4.examples/4.routing/middleware.md

@@ -1,9 +1,11 @@
 ---
-title: "Middleware"
-description: "This example shows how to add route middleware with the middleware/ directory or with a plugin, and how to use them globally or per page."
 toc: false
 ---
 
+# Middleware
+
+This example shows how to add route middleware with the middleware/ directory or with a plugin, and how to use them globally or per page.
+
 ::ReadMore{link="/guide/directory-structure/middleware"}
 ::
 

docs/content/4.examples/4.routing/nuxt-link.md

@@ -1,9 +1,11 @@
 ---
-title: "<NuxtLink>"
-description: "This example shows different ways to use <NuxtLink>."
 toc: false
 ---
 
+# `<NuxtLink>`
+
+This example shows different ways to navigate between page with the `<NuxtLink>` component.
+
 ::alert{type=info icon=💡}
 `components/MyNuxtLink.ts` defines a custom `<NuxtLink>`.
 ::

docs/content/4.examples/4.routing/pages.md

@@ -1,9 +1,11 @@
 ---
-title: "Pages"
-description: "This example shows how to use the pages/ directory to create application routes."
 toc: false
 ---
 
+# Pages
+
+This example shows how to use the pages/ directory to create application routes.
+
 ::ReadMore{link="/guide/directory-structure/pages"}
 ::
 

docs/content/4.examples/4.routing/universal-router.md

@@ -1,6 +1,4 @@
 ---
-title: "Universal Router"
-description: "This example demonstrates Nuxt universal routing utilities without depending on pages/ and vue-router."
 toc: false
 ---