@nuxt/docs 3.20.1 → 3.21.0

package/{2.guide/1.directory-structure → 2.directory-structure}/1.public.md

@@ -22,6 +22,6 @@ useSeoMeta({
 </script>
 ```
 
-::tip{to="https://v2.nuxt.com/docs/directory-structure/static" target="_blank"}
+::tip{to="https://v2.nuxt.com/docs/directory-structure/static/" target="_blank"}
 This is known as the [`static/`] directory in Nuxt 2.
 ::

package/{2.guide/1.directory-structure → 2.directory-structure}/1.server.md

@@ -58,7 +58,7 @@ export default defineEventHandler(() => 'Hello World!')
 Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
 
 ::note
-Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/3.x/guide/directory-structure/pages#dynamic-routes) do.
+Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/3.x/directory-structure/pages#dynamic-routes) do.
 ::
 
 ## Server Middleware
@@ -112,8 +112,6 @@ For example, you can define a custom handler utility that wraps the original han
 **Example:**
 
 ```ts [server/utils/handler.ts]
-import type { EventHandler, EventHandlerRequest } from 'h3'
-
 export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
   handler: EventHandler<T, D>,
 ): EventHandler<T, D> =>
@@ -130,6 +128,28 @@ export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
   })
 ```
 
+```ts [server/api/hello.get.ts]
+export default defineWrappedResponseHandler(event => 'hello world')
+```
+
+## Server Alias
+
+You can use the `#server` alias to import files from anywhere within the `server/` directory, regardless of the importing file's location.
+
+```ts [server/api/users/[id]/profile.ts]
+// Instead of relative paths like this:
+// import { formatUser } from '../../../utils/formatUser'
+
+// Use the #server alias:
+import { formatUser } from '#server/utils/formatUser'
+```
+
+This alias ensures consistent imports across your server code, especially useful in deeply nested route handlers.
+
+::note
+The `#server` alias can only be used within the `server/` directory. Importing from `#server` in client code will result in an error.
+::
+
 ## Server Types
 
 ::tip
@@ -168,7 +188,7 @@ You can now universally call this API on `/api/hello/nuxt` and get `Hello, nuxt!
 
 ### Matching HTTP Method
 
-Handle file names can be suffixed with `.get`, `.post`, `.put`, `.delete`, ... to match request's [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).
+Handle file names can be suffixed with `.get`, `.post`, `.put`, `.delete`, ... to match request's [HTTP Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods).
 
 ```ts [server/api/test.get.ts]
 export default defineEventHandler(() => 'Test get handler')
@@ -236,7 +256,7 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
-::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
+::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web/#runtime-type-safe-request-utils"}
 Alternatively, use `readValidatedBody` with a schema validator such as Zod for runtime and type safety.
 ::
 
@@ -287,8 +307,8 @@ export default defineEventHandler((event) => {
 
   if (!Number.isInteger(id)) {
     throw createError({
-      statusCode: 400,
-      statusMessage: 'ID should be an integer',
+      status: 400,
+      statusText: 'ID should be an integer',
     })
   }
   return 'All good'
@@ -402,7 +422,7 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/guide/concepts/server-engine"}
+:read-more{to="/docs/3.x/guide/concepts/server-engine"}
 
 ### Nested Router
 
@@ -464,7 +484,7 @@ Never combine `next()` callback with a legacy middleware that is `async` or retu
 
 ### Server Storage
 
-Nitro provides a cross-platform [storage layer](https://nitro.build/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](#server-plugins).
+Nitro provides a cross-platform [storage layer](https://nitro.build/guide/storage). In order to configure additional storage mount points, you can use `nitro.storage`, or [server plugins](/docs/3.x/directory-structure/server#server-plugins).
 
 **Example of adding a Redis storage:**
 

package/{2.guide/1.directory-structure → 2.directory-structure}/1.shared.md

@@ -41,7 +41,7 @@ export default function (input: string) {
 }
 ```
 
-You can now use [auto-imported](/docs/3.x/guide/directory-structure/shared#auto-imports) utilities in your Nuxt app and `server/` directory.
+You can now use [auto-imported](/docs/3.x/directory-structure/shared) utilities in your Nuxt app and `server/` directory.
 
 ```vue [app.vue]
 <script setup lang="ts">
@@ -68,10 +68,10 @@ export default defineEventHandler((event) => {
 Only files in the `shared/utils/` and `shared/types/` directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to `imports.dirs` and `nitro.imports.dirs`.
 
 ::tip
-The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`composables/`](/docs/3.x/guide/directory-structure/composables) and [`utils/`](/docs/3.x/guide/directory-structure/utils) directories.
+The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`composables/`](/docs/3.x/directory-structure/composables) and [`utils/`](/docs/3.x/directory-structure/utils) directories.
 ::
 
-:read-more{to="/docs/guide/directory-structure/composables#how-files-are-scanned"}
+:read-more{to="/docs/3.x/directory-structure/composables#how-files-are-scanned"}
 
 ```bash [Directory Structure]
 -| shared/
@@ -101,4 +101,4 @@ import upper from '#shared/utils/formatters/upper'
 
 This alias ensures consistent imports across your application, regardless of the importing file's location.
 
-:read-more{to="/docs/guide/concepts/auto-imports"}
+:read-more{to="/docs/3.x/guide/concepts/auto-imports"}

package/{2.guide/1.directory-structure → 2.directory-structure}/1.utils.md

@@ -5,7 +5,7 @@ description: Use the utils/ directory to auto-import your utility functions thro
 navigation.icon: i-vscode-icons-folder-type-tools
 ---
 
-The main purpose of the [`utils/` directory](/docs/3.x/guide/directory-structure/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
+The main purpose of the [`utils/` directory](/docs/3.x/directory-structure/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
 
 ## Usage
 
@@ -35,15 +35,15 @@ You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
 </template>
 ```
 
-:read-more{to="/docs/guide/concepts/auto-imports"}
+:read-more{to="/docs/3.x/guide/concepts/auto-imports"}
 
-:link-example{to="/docs/examples/features/auto-imports"}
+:link-example{to="/docs/3.x/examples/features/auto-imports"}
 
 ::tip
-The way `utils/` auto-imports work and are scanned is identical to the [`composables/`](/docs/3.x/guide/directory-structure/composables) directory.
+The way `utils/` auto-imports work and are scanned is identical to the [`composables/`](/docs/3.x/directory-structure/composables) directory.
 ::
 
 ::important
 These utils are only available within the Vue part of your app. :br
-Only `server/utils` are auto-imported in the [`server/`](/docs/3.x/guide/directory-structure/server#server-utilities) directory.
+Only `server/utils` are auto-imported in the [`server/`](/docs/3.x/directory-structure/server#server-utilities) directory.
 ::

package/{2.guide/1.directory-structure → 2.directory-structure}/2.env.md

@@ -6,7 +6,7 @@ navigation.icon: i-vscode-icons-file-type-dotenv
 ---
 
 ::important
-This file should be added to your [`.gitignore`](/docs/3.x/guide/directory-structure/gitignore) file to avoid pushing secrets to your repository.
+This file should be added to your [`.gitignore`](/docs/3.x/directory-structure/gitignore) file to avoid pushing secrets to your repository.
 ::
 
 ## Dev, Build and Generate Time
@@ -56,7 +56,7 @@ Since `.env` files are not used in production, you must explicitly set environme
 * Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
 
 ::important
-`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables).
+`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (https://nuxt.com/docs/3.x/guide/going-further/runtime-config#environment-variables).
 ::
 
 ## Production Preview
@@ -71,9 +71,9 @@ DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs
 
 Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.
 
-:read-more{to="/docs/guide/going-further/runtime-config"}
+:read-more{to="/docs/3.x/guide/going-further/runtime-config"}
 
 ::note
 If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively _within_ your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.
-:read-more{to="/docs/guide/directory-structure/app-config"}
+:read-more{to="/docs/3.x/directory-structure/app-config"}
 ::

package/{2.guide/1.directory-structure → 2.directory-structure}/2.nuxtignore.md

@@ -3,11 +3,12 @@ title: .nuxtignore
 head.title: '.nuxtignore'
 description: The .nuxtignore file lets Nuxt ignore files in your project’s root directory during the build phase.
 navigation.icon: i-vscode-icons-file-type-nuxt
+
 ---
 
 The `.nuxtignore` file tells Nuxt to ignore files in your project’s root directory ([`rootDir`](/docs/3.x/api/nuxt-config#rootdir)) during the build phase.
 
-It is subject to the same specification as [`.gitignore`](/docs/3.x/guide/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
+It is subject to the same specification as [`.gitignore`](/docs/3.x/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
 
 ::tip
 You can also configure [`ignoreOptions`](/docs/3.x/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/3.x/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/3.x/api/nuxt-config#ignore) in your `nuxt.config` file.

package/{2.guide/1.directory-structure → 2.directory-structure}/2.nuxtrc.md

@@ -2,13 +2,13 @@
 title: ".nuxtrc"
 description: "The .nuxtrc file allows you to define nuxt configurations in a flat syntax."
 head.title: ".nuxtrc"
-navigation.icon: i-vscode-icons-file-type-nuxt  
+navigation.icon: i-vscode-icons-file-type-nuxt
 ---
 
 The `.nuxtrc` file can be used to configure Nuxt with a flat syntax. It is based on [`unjs/rc9`](https://github.com/unjs/rc9).
 
 ::tip
-For more advanced configurations, use [`nuxt.config`](/docs/3.x/guide/directory-structure/nuxt-config).
+For more advanced configurations, use [`nuxt.config`](/docs/3.x/directory-structure/nuxt-config).
 ::
 
 ## Usage
@@ -23,6 +23,9 @@ devtools.enabled=true
 # Add Nuxt modules
 modules[]=@nuxt/image
 modules[]=nuxt-security
+
+# Module setups (automatically added by Nuxt)
+setups.@nuxt/test-utils="3.23.0"
 ```
 
 If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.
@@ -31,7 +34,7 @@ If present, the properties in the `nuxt.config` file will overwrite the properti
 Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/3.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.
 ::
 
-::read-more{to="/docs/api/configuration/nuxt-config"}
+::read-more{to="/docs/3.x/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::
 

package/{2.guide/1.directory-structure → 2.directory-structure}/3.app-config.md

@@ -5,7 +5,7 @@ description: Expose reactive configuration within your application with the App
 navigation.icon: i-vscode-icons-file-type-light-config
 ---
 
-Nuxt provides an `app.config` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).
+Nuxt provides an `app.config.ts` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).
 
 You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions.
 
@@ -59,7 +59,7 @@ console.log(appConfig) // { foo: 'baz' }
 </script>
 ```
 
-::read-more{to="/docs/api/utils/update-app-config"}
+::read-more{to="/docs/3.x/api/utils/update-app-config"}
 Read more about the `updateAppConfig` utility.
 ::
 

package/{2.guide/1.directory-structure → 2.directory-structure}/3.app.md

@@ -13,7 +13,7 @@ If you have a `pages/` directory, the `app.vue` file is optional. Nuxt will auto
 
 ### Minimal Usage
 
-With Nuxt, the [`pages/`](/docs/3.x/guide/directory-structure/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
+With Nuxt, the [`pages/`](/docs/3.x/directory-structure/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
 
 ```vue [app.vue]
 <template>
@@ -21,11 +21,11 @@ With Nuxt, the [`pages/`](/docs/3.x/guide/directory-structure/pages) directory i
 </template>
 ```
 
-:link-example{to="/docs/examples/hello-world"}
+:link-example{to="/docs/3.x/examples/hello-world"}
 
 ### Usage with Pages
 
-When you have a [`pages/`](/docs/3.x/guide/directory-structure/pages) directory, you need to use the [`<NuxtPage>`](/docs/3.x/api/components/nuxt-page) component to display the current page:
+When you have a [`pages/`](/docs/3.x/directory-structure/pages) directory, you need to use the [`<NuxtPage>`](/docs/3.x/api/components/nuxt-page) component to display the current page:
 
 ```vue [app.vue]
 <template>
@@ -51,7 +51,7 @@ You can also define the common structure of your application directly in `app.vu
 Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
 ::
 
-::read-more{to="/docs/guide/directory-structure/pages"}
+::read-more{to="/docs/3.x/directory-structure/pages"}
 Learn more about how to structure your pages using the `pages/` directory.
 ::
 
@@ -67,6 +67,6 @@ When your application requires different layouts for different pages, you can us
 </template>
 ```
 
-::read-more{to="/docs/guide/directory-structure/layouts"}
+::read-more{to="/docs/3.x/directory-structure/layouts"}
 Learn more about how to structure your layouts using the `layouts/` directory.
 ::

package/{2.guide/1.directory-structure → 2.directory-structure}/3.error.md

@@ -11,14 +11,12 @@ During the lifespan of your application, some errors may appear unexpectedly at
 <script setup lang="ts">
 import type { NuxtError } from '#app'
 
-const props = defineProps({
-  error: Object as () => NuxtError,
-})
+const props = defineProps<{ error: NuxtError }>()
 </script>
 
 <template>
   <div>
-    <h1>{{ error.statusCode }}</h1>
+    <h1>{{ error.status }}</h1>
     <NuxtLink to="/">Go back home</NuxtLink>
   </div>
 </template>
@@ -33,12 +31,16 @@ The error page has a single prop - `error` which contains an error for you to ha
 The `error` object provides the following fields:
 ```ts
 interface NuxtError {
-  statusCode: number
+  status: number
   fatal: boolean
   unhandled: boolean
-  statusMessage?: string
+  statusText?: string
   data?: unknown
   cause?: unknown
+  // legacy/deprecated equivalent of `status`
+  statusCode: number
+  // legacy/deprecated equivalent of `statusText`
+  statusMessage?: string
 }
 ```
 
@@ -46,8 +48,8 @@ If you have an error with custom fields they will be lost; you should assign the
 
 ```ts
 throw createError({
-  statusCode: 404,
-  statusMessage: 'Page Not Found',
+  status: 404,
+  statusText: 'Page Not Found',
   data: {
     myCustomField: true,
   },

package/{2.guide/1.directory-structure → 2.directory-structure}/3.nuxt-config.md

@@ -27,8 +27,8 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="/docs/api/configuration/nuxt-config"}
+::read-more{to="/docs/3.x/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::
 
-To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/3.x/guide/directory-structure/env), [`.nuxtignore`](/docs/3.x/guide/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/3.x/guide/directory-structure/nuxtrc) dotfiles.
+To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/3.x/directory-structure/env), [`.nuxtignore`](/docs/3.x/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/3.x/directory-structure/nuxtrc) dotfiles.

package/{2.guide/1.directory-structure → 2.directory-structure}/3.package.md

@@ -27,6 +27,6 @@ The minimal `package.json` of your Nuxt application should looks like:
 }
 ```
 
-::read-more{icon="i-simple-icons-npm" to="https://docs.npmjs.com/cli/configuring-npm/package-json" target="_blank"}
+::read-more{icon="i-simple-icons-npm" to="https://docs.npmjs.com/cli/configuring-npm/package-json/" target="_blank"}
 Read more about the `package.json` file.
 ::

package/{2.guide/1.directory-structure → 2.directory-structure}/3.tsconfig.md

@@ -1,13 +1,13 @@
 ---
 title: "tsconfig.json"
-description: "Nuxt generates a .nuxt/tsconfig.json file with sensible defaults and your aliases."
+description: "Learn how Nuxt manages TypeScript configuration across different parts of your project."
 head.title: "tsconfig.json"
 navigation.icon: i-vscode-icons-file-type-tsconfig
 ---
 
 Nuxt [automatically generates](/docs/3.x/guide/concepts/typescript) a `.nuxt/tsconfig.json` file with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
 
-You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
+Your Nuxt project should include the following `tsconfig.json` file at the root of the project:
 
 ```json [tsconfig.json]
 {
@@ -28,6 +28,7 @@ If you need to customize your `paths`, this will override the auto-generated pat
 You can customize the TypeScript configuration of your Nuxt project for each context (`app` and `server`) in the `nuxt.config.ts` file.
 <!-- @case-police-ignore tsConfig -->
 ```ts twoslash [nuxt.config.ts]
+// @errors: 2353
 export default defineNuxtConfig({
   typescript: {
     // customize tsconfig.app.json

package/2.directory-structure/index.md

@@ -0,0 +1,65 @@
+---
+title: 'Nuxt Directory Structure'
+description: 'Learn about the directory structure of a Nuxt application and how to use it.'
+navigation: false
+---
+
+Nuxt applications have a specific directory structure that is used to organize the code. This structure is designed to be easy to understand and to be used in a consistent way.
+
+## Root Directory
+
+The root directory of a Nuxt application is the directory that contains the `nuxt.config.ts` file. This file is used to configure the Nuxt application.
+
+## App Directory
+
+The following directories are related to the universal Nuxt application:
+- [`assets/`](/docs/3.x/directory-structure/assets): website's assets that the build tool (Vite or webpack) will process
+- [`components/`](/docs/3.x/directory-structure/components): Vue components of the application
+- [`composables/`](/docs/3.x/directory-structure/composables): add your Vue composables
+- [`layouts/`](/docs/3.x/directory-structure/layouts): Vue components that wrap around your pages and avoid re-rendering between pages
+- [`middleware/`](/docs/3.x/directory-structure/middleware): run code before navigating to a particular route
+- [`pages/`](/docs/3.x/directory-structure/pages): file-based routing to create routes within your web application
+- [`plugins/`](/docs/3.x/directory-structure/plugins): use Vue plugins and more at the creation of your Nuxt application
+- [`utils/`](/docs/3.x/directory-structure/utils): add functions throughout your application that can be used in your components, composables, and pages.
+
+This directory also includes specific files:
+- [`app.config.ts`](/docs/3.x/directory-structure/app-config): a reactive configuration within your application
+- [`app.vue`](/docs/3.x/directory-structure/app): the root component of your Nuxt application
+- [`error.vue`](/docs/3.x/directory-structure/error): the error page of your Nuxt application
+
+## Public Directory
+
+The [`public/`](/docs/3.x/directory-structure/public) directory is the directory that contains the public files of the Nuxt application. Files contained within this directory are served at the root and are not modified by the build process.
+
+This is suitable for files that have to keep their names (e.g. `robots.txt`) _or_ likely won't change (e.g. `favicon.ico`).
+
+## Server Directory
+
+The [`server/`](/docs/3.x/directory-structure/server) directory is the directory that contains the server-side code of the Nuxt application. It contains the following subdirectories:
+- [`api/`](/docs/3.x/directory-structure/server#server-routes): contains the API routes of the application.
+- [`routes/`](/docs/3.x/directory-structure/server#server-routes): contains the server routes of the application (e.g. dynamic `/sitemap.xml`).
+- [`middleware/`](/docs/3.x/directory-structure/server#server-middleware): run code before a server route is processed
+- [`plugins/`](/docs/3.x/directory-structure/server#server-plugins): use plugins and more at the creation of the Nuxt server
+- [`utils/`](/docs/3.x/directory-structure/server#server-utilities): add functions throughout your application that can be used in your server  code.
+
+## Shared Directory
+
+The [`shared/`](/docs/3.x/directory-structure/shared) directory is the directory that contains the shared code of the Nuxt application and Nuxt server. This code can be used in both the Vue app and the Nitro server.
+
+## Content Directory
+
+The [`content/`](/docs/3.x/directory-structure/content) directory is enabled by the [Nuxt Content](https://content.nuxt.com) module. It is used to create a file-based CMS for your application using Markdown files.
+
+## Modules Directory
+
+The [`modules/`](/docs/3.x/directory-structure/modules) directory is the directory that contains the local modules of the Nuxt application. Modules are used to extend the functionality of the Nuxt application.
+
+## Layers Directory
+
+The [`layers/`](/docs/3.x/directory-structure/layers) directory allows you to organize and share reusable code, components, composables, and configurations. Layers within this directory are automatically registered in your project.
+
+## Nuxt Files
+
+- [`nuxt.config.ts`](/docs/3.x/directory-structure/nuxt-config) file is the main configuration file for the Nuxt application.
+- [`.nuxtrc`](/docs/3.x/directory-structure/nuxtrc) file is another syntax for configuring the Nuxt application (useful for global configurations).
+- [`.nuxtignore`](/docs/3.x/directory-structure/nuxtignore) file is used to ignore files in the root directory during the build phase.

package/3.guide/0.index.md

@@ -0,0 +1,28 @@
+---
+title: 'Nuxt Guide'
+titleTemplate: '%s'
+description: 'Learn how Nuxt works with in-depth guides.'
+navigation: false
+surround: false
+---
+
+::card-group{class="sm:grid-cols-1"}
+  ::card{icon="i-lucide-medal" title="Key Concepts" to="/docs/3.x/guide/concepts"}
+  Discover the main concepts behind Nuxt, from auto-import, hybrid rendering to its TypeScript support.
+  ::
+  ::card{icon="i-lucide-square-check" title="Best Practices" to="/docs/3.x/guide/best-practices"}
+  Learn about best practices when developing with Nuxt.
+  ::
+  ::card{icon="i-lucide-bot" title="Working with AI" to="/docs/4.x/guide/ai"}
+  Integrate AI tools into your Nuxt workflow with MCP Server and LLMs.txt.
+  ::
+  ::card{icon="i-lucide-box" title="Module Author Guide" to="/docs/3.x/guide/modules"}
+  Learn how to create Nuxt modules to integrate, enhance or extend any Nuxt application.
+  ::
+  ::card{icon="i-lucide-book-open" title="Recipes" to="/docs/3.x/guide/recipes"}
+  Find solutions to common problems and learn how to implement them in your Nuxt project.
+  ::
+  ::card{icon="i-lucide-star" title="Going Further" to="/docs/3.x/guide/going-further"}
+  Master Nuxt with advanced concepts like experimental features, hooks, and more.
+  ::
+::

package/{2.guide/2.concepts/3.rendering.md → 3.guide/1.concepts/1.rendering.md}

@@ -3,7 +3,7 @@ title: 'Rendering Modes'
 description: 'Learn about the different rendering modes available in Nuxt.'
 ---
 
-Nuxt supports different rendering modes, [universal rendering](#universal-rendering), [client-side rendering](#client-side-rendering) but also offers [hybrid-rendering](#hybrid-rendering) and the possibility to render your application on [CDN Edge Servers](#edge-side-rendering).
+Nuxt supports different rendering modes, [universal rendering](/docs/3.x/guide/concepts/rendering#universal-rendering), [client-side rendering](/docs/3.x/guide/concepts/rendering#client-side-rendering) but also offers [hybrid-rendering](/docs/3.x/guide/concepts/rendering#hybrid-rendering) and the possibility to render your application on [CDN Edge Servers](/docs/3.x/guide/concepts/rendering#edge-side-rendering).
 
 Both the browser and server can interpret JavaScript code to turn Vue.js components into HTML elements. This step is called **rendering**. Nuxt supports both **universal** and **client-side** rendering. The two approaches have benefits and downsides that we will cover.
 
@@ -44,7 +44,7 @@ const handleClick = () => {
 
 On the initial request, the `counter` ref is initialized in the server since it is rendered inside the `<p>` tag. The contents of `handleClick` is never executed here. During hydration in the browser, the `counter` ref is re-initialized. The `handleClick` finally binds itself to the button; Therefore it is reasonable to deduce that the body of `handleClick` will always run in a browser environment.
 
-[Middlewares](/docs/3.x/guide/directory-structure/middleware) and [pages](/docs/3.x/guide/directory-structure/pages) run in the server and on the client during hydration. [Plugins](/docs/3.x/guide/directory-structure/plugins) can be rendered on the server or client or both. [Components](/docs/3.x/guide/directory-structure/components) can be forced to run on the client only as well. [Composables](/docs/3.x/guide/directory-structure/composables) and [utilities](/docs/3.x/guide/directory-structure/utils) are rendered based on the context of their usage.
+[Middlewares](/docs/3.x/directory-structure/middleware) and [pages](/docs/3.x/directory-structure/pages) run in the server and on the client during hydration. [Plugins](/docs/3.x/directory-structure/plugins) can be rendered on the server or client or both. [Components](/docs/3.x/directory-structure/components) can be forced to run on the client only as well. [Composables](/docs/3.x/directory-structure/composables) and [utilities](/docs/3.x/directory-structure/utils) are rendered based on the context of their usage.
 
 **Benefits of server-side rendering:**
 - **Performance**: Users can get immediate access to the page's content because browsers can display static content much faster than JavaScript-generated content. At the same time, Nuxt preserves the interactivity of a web application during the hydration process.
@@ -52,12 +52,12 @@ On the initial request, the `counter` ref is initialized in the server since it
 
 **Downsides of server-side rendering:**
 - **Development constraints:** Server and browser environments don't provide the same APIs, and it can be tricky to write code that can run on both sides seamlessly. Fortunately, Nuxt provides guidelines and specific variables to help you determine where a piece of code is executed.
-- **Cost:** A server needs to be running in order to render pages on the fly. This adds a monthly cost like any traditional server. However, the server calls are highly reduced thanks to universal rendering with the browser taking over on client-side navigation. A cost reduction is possible by leveraging [edge-side-rendering](#edge-side-rendering).
+- **Cost:** A server needs to be running in order to render pages on the fly. This adds a monthly cost like any traditional server. However, the server calls are highly reduced thanks to universal rendering with the browser taking over on client-side navigation. A cost reduction is possible by leveraging [edge-side-rendering](/docs/3.x/guide/concepts/rendering#edge-side-rendering).
 
 Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: **blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.**
 
 ::tip
-For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch).
+For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr#hydration-mismatch).
 ::
 
 ::important
@@ -91,7 +91,7 @@ export default defineNuxtConfig({
 
 ::note
 If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
-:read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
+:read-more{title="SPA Loading Template" to="/docs/3.x/api/configuration/nuxt-config#spaloadingtemplate"}
 ::
 
 :video-accordion{title="Watch a video from Alexander Lichter about Building a plain SPA with Nuxt" videoId="7Lr0QTP1Ro8"}
@@ -131,6 +131,7 @@ The `200.html` and `404.html` might be useful for the hosting provider you are u
 When prerendering a client-rendered app, Nuxt will generate `index.html`, `200.html` and `404.html` files by default. However, if you need to prevent any (or all) of these files from being generated in your build, you can use the `'prerender:generate'` hook from [Nitro](/docs/3.x/getting-started/prerendering#prerendergenerate-nitro-hook).
 
 ```ts twoslash [nuxt.config.ts]
+// @errors: 2353 7006
 export default defineNuxtConfig({
   ssr: false,
   nitro: {
@@ -225,33 +226,7 @@ Edge-side rendering is possible thanks to [Nitro](https://nitro.build/), the [se
 
 The current platforms where you can leverage ESR are:
 - [Cloudflare Pages](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command
-- [Vercel Edge Functions](https://vercel.com/features/edge-functions) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
-- [Netlify Edge Functions](https://www.netlify.com/products/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable
+- [Vercel Cloud](https://vercel.com/home) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
+- [Netlify Edge Functions](https://www.netlify.com/platform/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable
 
 Note that **Hybrid Rendering** can be used when using Edge-Side Rendering with route rules.
-
-You can explore open source examples deployed on some of the platform mentioned above:
-::card-group
-  ::card
-  ---
-  icon: i-simple-icons-github
-  title: Nuxt Todos Edge
-  to: https://github.com/atinux/nuxt-todos-edge
-  target: _blank
-  ui.icon.base: text-black dark:text-white
-  ---
-  A todos application with user authentication, SSR and SQLite.
-  ::
-  ::card
-  ---
-  icon: i-simple-icons-github
-  title: Atinotes
-  to: https://github.com/atinux/atinotes
-  target: _blank
-  ui.icon.base: text-black dark:text-white
-  ---
-  An editable website with universal rendering based on Cloudflare KV.
-  ::
-::
-
-<!-- TODO: link to templates with ESR category for examples -->