@nuxt/docs 4.0.0 → 4.0.2

package/1.getting-started/01.introduction.md

@@ -24,7 +24,7 @@ Nuxt uses conventions and an opinionated directory structure to automate repetit
 - **Server-side rendering out of the box:** Nuxt comes with built-in SSR capabilities, so you don't have to set up a separate server yourself.
 - **Auto-imports:** write Vue composables and components in their respective directories and use them without having to import them with the benefits of tree-shaking and optimized JS bundles.
 - **Data-fetching utilities:** Nuxt provides composables to handle SSR-compatible data fetching as well as different strategies.
-- **Zero-config TypeScript support:** write type-safe code without having to learn TypeScript with our auto-generated types and `tsconfig.json`
+- **Zero-config TypeScript support:** write type-safe code without having to learn TypeScript with our auto-generated types and `tsconfig.json`.
 - **Configured build tools:** we use [Vite](https://vite.dev) by default to support hot module replacement (HMR) in development and bundling your code for production with best-practices baked-in.
 
 Nuxt takes care of these and provides both frontend and backend functionality so you can focus on what matters: **creating your web application**.
@@ -64,7 +64,7 @@ A Nuxt application can be deployed on a Node or Deno server, pre-rendered to be
 
 ### Modular
 
-A module system allows to extend Nuxt with custom features and integrations with third-party services.
+A module system allows you to extend Nuxt with custom features and integrations with third-party services.
 
 :read-more{title="Nuxt Modules Concept" to="/docs/guide/concepts/modules"}
 

package/1.getting-started/02.installation.md

@@ -9,8 +9,8 @@ navigation.icon: i-lucide-play
 If you just want to play around with Nuxt in your browser without setting up a project, you can use one of our online sandboxes:
 
 ::card-group
-  :card{title="Open on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v3" target="_blank"}
-  :card{title="Open on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v3" target="_blank"}
+  :card{title="Open on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v4" target="_blank"}
+  :card{title="Open on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v4" target="_blank"}
 ::
 
 Or follow the steps below to set up a new Nuxt project on your computer.
@@ -39,23 +39,23 @@ Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.
 ::code-group{sync="pm"}
 
 ```bash [npm]
-npm create nuxt <project-name> -- -t v4
+npm create nuxt@latest <project-name>
 ```
 
 ```bash [yarn]
-yarn create nuxt <project-name> -t v4
+yarn create nuxt@latest <project-name>
 ```
 
 ```bash [pnpm]
-pnpm create nuxt <project-name> -t v4
+pnpm create nuxt@latest <project-name>
 ```
 
 ```bash [bun]
-bun create nuxt <project-name> -t v4
+bun create nuxt@latest <project-name>
 ```
 
 ```bash [deno]
-deno -A npm:create-nuxt@latest <project-name> -t v4
+deno -A npm:create-nuxt@latest <project-name>
 ```
 
 ::

package/1.getting-started/03.configuration.md

@@ -100,7 +100,7 @@ const runtimeConfig = useRuntimeConfig()
 
 ## App Configuration
 
-The `app.config.ts` file, located in the source directory (by default the root of the project), is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overridden using environment variables.
+The `app.config.ts` file, located in the source directory (by default the root of the project), is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these cannot be overridden using environment variables.
 
 A minimal configuration file exports the `defineAppConfig` function containing an object with your configuration. The `defineAppConfig` helper is globally available without import.
 

package/1.getting-started/04.views.md

@@ -88,7 +88,7 @@ To use pages, create `pages/index.vue` file and add `<NuxtPage />` component to
 
 ![Layouts are wrapper around pages](/assets/docs/getting-started/views/layouts.svg)
 
-Layouts are wrappers around pages that contain a common User Interface for several pages, such as a header and footer display. Layouts are Vue files using `<slot />` components to display the **page** content. The `layouts/default.vue` file will be used by default. Custom layouts can be set as part of your page metadata.
+Layouts are wrappers around pages that contain a common User Interface for several pages, such as header and footer displays. Layouts are Vue files using `<slot />` components to display the **page** content. The `layouts/default.vue` file will be used by default. Custom layouts can be set as part of your page metadata.
 
 ::note
 If you only have a single layout in your application, we recommend using [`app.vue`](/docs/guide/directory-structure/app) with [`<NuxtPage />`](/docs/api/components/nuxt-page) instead.

package/1.getting-started/06.styling.md

@@ -51,7 +51,7 @@ The stylesheets will be inlined in the HTML rendered by Nuxt, injected globally
 
 ### Working With Fonts
 
-Place your local fonts files in your `~/public/` directory, for example in `~/public/fonts`. You can then reference them in your stylesheets using `url()`.
+Place your local fonts files in your `public/` directory, for example in `public/fonts`. You can then reference them in your stylesheets using `url()`.
 
 ```css [assets/css/main.css]
 @font-face {
@@ -119,7 +119,7 @@ export default defineNuxtConfig({
 
 ## External Stylesheets
 
-You can include external stylesheets in your application by adding a link element in the head section of your nuxt.config file. You can achieve this result using different methods. Note that local stylesheets can also be included like this.
+You can include external stylesheets in your application by adding a link element in the head section of your nuxt.config file. You can achieve this result using different methods. Note that local stylesheets can also be included this way.
 
 You can manipulate the head with the [`app.head`](/docs/api/nuxt-config#head) property of your Nuxt configuration:
 
@@ -409,7 +409,7 @@ You can use [CSS Modules](https://github.com/css-modules/css-modules) with the m
 
 ### Preprocessors Support
 
-SFC style blocks support preprocessors syntax. Vite come with built-in support for .scss, .sass, .less, .styl and .stylus files without configuration. You just need to install them first, and they will be available directly in SFC with the lang attribute.
+SFC style blocks support preprocessor syntax. Vite comes with built-in support for .scss, .sass, .less, .styl and .stylus files without configuration. You just need to install them first, and they will be available directly in SFC with the lang attribute.
 
 ::code-group
 

package/1.getting-started/08.seo-meta.md

@@ -12,7 +12,7 @@ and numerous configuration options to manage your app's head and SEO meta tags.
 Providing an [`app.head`](/docs/api/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) allows you to statically customize the head for your entire app.
 
 ::important
-This method does not allow you to provide reactive data. We recommend to use `useHead()` in `app.vue`.
+This method does not allow you to provide reactive data. We recommend using `useHead()` in `app.vue`.
 ::
 
 It's good practice to set tags here that won't change such as your site title default, language and favicon.
@@ -75,7 +75,7 @@ useHead({
 </script>
 ```
 
-We recommend to take a look at the [`useHead`](/docs/api/composables/use-head) and [`useHeadSafe`](/docs/api/composables/use-head-safe) composables.
+We recommend taking a look at the [`useHead`](/docs/api/composables/use-head) and [`useHeadSafe`](/docs/api/composables/use-head-safe) composables.
 
 ## `useSeoMeta`
 

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

@@ -16,7 +16,7 @@ You can enable page transitions to apply an automatic transition for all your [p
 export default defineNuxtConfig({
   app: {
     pageTransition: { name: 'page', mode: 'out-in' }
-  },
+  }
 })
 ```
 
@@ -121,7 +121,7 @@ You can enable layout transitions to apply an automatic transition for all your
 export default defineNuxtConfig({
   app: {
     layoutTransition: { name: 'layout', mode: 'out-in' }
-  },
+  }
 })
 ```
 
@@ -470,4 +470,4 @@ export default defineNuxtRouteMiddleware(to => {
 
 ### Known Issues
 
-- If you perform data fetching within your page setup functions, that you may wish to reconsider using this feature for the moment. (By design, View Transitions completely freeze DOM updates whilst they are taking place.) We're looking at restrict the View Transition to the final moments before `<Suspense>` resolves, but in the interim you may want to consider carefully whether to adopt this feature if this describes you.
+- If you perform data fetching within your page setup functions, you may wish to reconsider using this feature for the moment. (By design, View Transitions completely freeze DOM updates whilst they are taking place.) We're looking at restricting the View Transition to the final moments before `<Suspense>` resolves, but in the interim you may want to consider carefully whether to adopt this feature if this describes you.

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

@@ -9,7 +9,7 @@ Nuxt comes with two composables and a built-in library to perform data-fetching
 In a nutshell:
 
 - [`$fetch`](/docs/api/utils/dollarfetch) is the simplest way to make a network request.
-- [`useFetch`](/docs/api/composables/use-fetch) is wrapper around `$fetch` that fetches data only once in [universal rendering](/docs/guide/concepts/rendering#universal-rendering).
+- [`useFetch`](/docs/api/composables/use-fetch) is a wrapper around `$fetch` that fetches data only once in [universal rendering](/docs/guide/concepts/rendering#universal-rendering).
 - [`useAsyncData`](/docs/api/composables/use-async-data) is similar to `useFetch` but offers more fine-grained control.
 
 Both `useFetch` and `useAsyncData` share a common set of options and patterns that we will detail in the last sections.
@@ -81,7 +81,7 @@ 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.
+It is recommended to use `$fetch` for client-side interactions (event-based) or combined with [`useAsyncData`](#useasyncdata) when fetching the initial component data.
 ::
 
 ::read-more{to="/docs/api/utils/dollarfetch"}
@@ -483,7 +483,7 @@ If you need to change the URL based on a reactive value, you may want to use a [
 
 #### Computed URL
 
-Sometimes you may need to compute an URL from reactive values, and refresh the data each time these change. Instead of juggling your way around, you can attach each param as a reactive value. Nuxt will automatically use the reactive value and re-fetch each time it changes.
+Sometimes you may need to compute a URL from reactive values, and refresh the data each time these change. Instead of juggling your way around, you can attach each param as a reactive value. Nuxt will automatically use the reactive value and re-fetch each time it changes.
 
 ```vue
 <script setup lang="ts">

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

@@ -109,7 +109,7 @@ const handleError = () => clearError({ redirect: '/' })
 Read more about `error.vue` and its uses.
 ::
 
-For custom errors we highly recommend to use `onErrorCaptured` composable that can be called in a page/component setup function or `vue:error` runtime nuxt hook that can be configured in a nuxt plugin.
+For custom errors we highly recommend using `onErrorCaptured` composable that can be called in a page/component setup function or `vue:error` runtime nuxt hook that can be configured in a nuxt plugin.
 
 ```ts twoslash [plugins/error-handler.ts]
 export default defineNuxtPlugin(nuxtApp => {

package/1.getting-started/15.prerendering.md

@@ -99,7 +99,7 @@ export default defineNuxtConfig({
 });
 ```
 
-::read-more{to="https://nitro.build/config/#routerules"}
+::read-more{to="https://nitro.build/config#routerules"}
 Read more about Nitro's `routeRules` configuration.
 ::
 
@@ -177,7 +177,7 @@ export default defineNuxtConfig({
 
 ### `prerender:generate` Nitro hook
 
-This is called for each route during prerendering. You can use this for fine grained handling of each route that gets prerendered.
+This is called for each route during prerendering. You can use this for fine-grained handling of each route that gets prerendered.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({

package/1.getting-started/16.deployment.md

@@ -62,7 +62,7 @@ By default, the workload gets distributed to the workers with the round robin st
 
 ### Learn More
 
-:read-more{to="https://nitro.build/deploy/node" title="the Nitro documentation for node-server preset"}
+:read-more{to="https://nitro.build/deploy/runtimes/node" title="the Nitro documentation for node-server preset"}
 
 :video-accordion{title="Watch Daniel Roe's short video on the topic" videoId="0x1H6K5yOfs"}
 

package/1.getting-started/17.testing.md

@@ -63,7 +63,7 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
 
 ::tip
 When importing `@nuxt/test-utils` in your vitest config, It is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.
-> ie. `vitest.config.m{ts,js}`.
+> i.e., `vitest.config.m{ts,js}`.
 ::
 
 ::tip

package/1.getting-started/18.upgrade.md

@@ -43,19 +43,19 @@ First, upgrade to Nuxt 4:
 ::code-group{sync="pm"}
 
 ```bash [npm]
-npm install nuxt@^4.0.0-rc
+npm install nuxt@^4.0.0
 ```
 
 ```bash [yarn]
-yarn add nuxt@^4.0.0-rc
+yarn add nuxt@^4.0.0
 ```
 
 ```bash [pnpm]
-pnpm add nuxt@^4.0.0-rc
+pnpm add nuxt@^4.0.0
 ```
 
 ```bash [bun]
-bun add nuxt@^4.0.0-rc
+bun add nuxt@^4.0.0
 ```
 
 ::
@@ -140,6 +140,7 @@ layers/
 modules/
 node_modules/
 public/
+shared/
 server/
   api/
   middleware/
@@ -430,7 +431,7 @@ export default defineNuxtPlugin({
 })
 ```
 
-While not required it's recommend to update any imports from `@unhead/vue` to `#imports` or `nuxt/app`.
+While not required it's recommended to update any imports from `@unhead/vue` to `#imports` or `nuxt/app`.
 
 ```diff
 -import { useHead } from '@unhead/vue'
@@ -974,7 +975,41 @@ const importName = genSafeVariableName
 You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes`
 ::
 
-### TypeScript Configuration Changes
+### Default TypeScript Configuration Changes
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+`compilerOptions.noUncheckedIndexedAccess` is now `true` instead of `false`.
+
+#### Reasons for Change
+
+This change is a follow up to a prior [3.12 config update](https://github.com/nuxt/nuxt/pull/27485) where we improved our defaults, mostly adhering to [TotalTypeScript's recommendations](https://www.totaltypescript.com/tsconfig-cheat-sheet).
+
+#### Migration Steps
+
+There are two approaches:
+
+1. Run a typecheck on your app and fix any new errors (recommended).
+
+2. Override the new default in your `nuxt.config.ts`:
+
+   <!-- @case-police-ignore tsConfig -->
+
+   ```ts
+   export default defineNuxtConfig({
+     typescript: {
+       tsConfig: {
+         compilerOptions: {
+           noUncheckedIndexedAccess: false
+         }
+       }
+     }
+   })
+   ```
+
+### TypeScript Configuration Splitting
 
 🚦 **Impact Level**: Minimal
 
@@ -1121,7 +1156,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{to="https://nitro.build/config/#prerender"}
+::read-more{to="https://nitro.build/config#prerender"}
 Read more about Nitro's prerender configuration options.
 ::
 

package/2.guide/0.index.md

@@ -19,4 +19,7 @@ surround: false
   ::card{icon="i-lucide-book-open" title="Recipes" to="/docs/guide/recipes"}
   Find solutions to common problems and learn how to implement them in your Nuxt project.
   ::
+  ::card{icon="i-lucide-square-check" title="Best Practices" to="/docs/guide/best-practices"}
+  Learn about best practices when developing with Nuxt
+  ::
 ::

package/2.guide/1.concepts/3.rendering.md

@@ -70,7 +70,7 @@ Out of the box, a traditional Vue.js application is rendered in the browser (or
 
 **Benefits of client-side rendering:**
 - **Development speed**: When working entirely on the client-side, we don't have to worry about the server compatibility of the code, for example, by using browser-only APIs like the `window` object.
-- **Cheaper:** Running a server adds a cost of infrastructure as you would need to run on a platform that supports JavaScript. We can host Client-only applications on any static server with HTML, CSS, and JavaScript files.
+- **Cheaper:** Running a server adds a cost of infrastructure as you would need to run on a platform that supports JavaScript. We can host client-only applications on any static server with HTML, CSS, and JavaScript files.
 - **Offline:** Because code entirely runs in the browser, it can nicely keep working while the internet is unavailable.
 
 **Downsides of client-side rendering:**

package/2.guide/2.directory-structure/1.app/1.components.md

@@ -79,7 +79,7 @@ const MyButton = resolveComponent('MyButton')
 ```
 
 ::important
-If you are using `resolveComponent` to handle dynamic components, make sure not to insert anything but the name of the component, which must be a literal string and not be or contain a variable. The string is statically analyzed at compilation step.
+If you are using `resolveComponent` to handle dynamic components, make sure not to insert anything but the name of the component, which must be a literal string and not be or contain a variable. The string is statically analyzed at the compilation step.
 ::
 
 :video-accordion{title="Watch Daniel Roe's short video about resolveComponent()" videoId="4kq8E5IUM2U"}

package/2.guide/2.directory-structure/1.app/1.pages.md

@@ -377,7 +377,7 @@ Learn more about `<NuxtLink>` usage.
 Nuxt allows programmatic navigation through the `navigateTo()` utility method. Using this utility method, you will be able to programmatically navigate the user in your app. This is great for taking input from the user and navigating them dynamically throughout your application. In this example, we have a simple method called `navigate()` that gets called when the user submits a search form.
 
 ::note
-Ensure to always `await` on `navigateTo` or chain its result by returning from functions.
+Make sure to always `await` on `navigateTo` or chain its result by returning from functions.
 ::
 
 ```vue twoslash

package/2.guide/3.going-further/11.nightly-release-channel.md

@@ -26,8 +26,8 @@ Update `nuxt` dependency inside `package.json`:
 ```diff [package.json]
 {
   "devDependencies": {
---    "nuxt": "^3.0.0"
-++    "nuxt": "npm:nuxt-nightly@3x"
+--    "nuxt": "^4.0.0"
+++    "nuxt": "npm:nuxt-nightly@latest"
   }
 }
 ```
@@ -41,8 +41,8 @@ Update `nuxt` dependency inside `package.json`:
 ```diff [package.json]
 {
   "devDependencies": {
---    "nuxt": "npm:nuxt-nightly@3x"
-++    "nuxt": "^3.0.0"
+--    "nuxt": "npm:nuxt-nightly@latest"
+++    "nuxt": "^4.0.0"
   }
 }
 ```

package/2.guide/3.going-further/3.modules.md

@@ -785,7 +785,7 @@ Linking to the integration website and documentation is always a good idea.
 
 #### Provide a StackBlitz Demo or Boilerplate
 
-It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v3) that you add to your module readme.
+It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v4) that you add to your module readme.
 
 This not only provides potential users of your module a quick and easy way to experiment with the module but also an easy way for them to build minimal reproductions they can send you when they encounter issues.
 
@@ -813,7 +813,7 @@ Watch Vue School video about Nuxt module types.
 
 **Community modules** are modules prefixed (scoped) with `@nuxtjs/` (e.g. [`@nuxtjs/tailwindcss`](https://tailwindcss.nuxtjs.org)). They are proven modules made and maintained by community members. Again, contributions are welcome from anyone.
 
-**Third party and other community modules** are modules (often) prefixed with `nuxt-`. Anyone can make them, using this prefix allows these modules to be discoverable on npm. This is the best starting point to draft and try an idea!
+**Third-party and other community modules** are modules (often) prefixed with `nuxt-`. Anyone can make them, using this prefix allows these modules to be discoverable on npm. This is the best starting point to draft and try an idea!
 
 **Private or personal modules** are modules made for your own use case or company. They don't need to follow any naming rules to work with Nuxt and are often seen scoped under an npm organization (e.g. `@my-company/nuxt-auth`)
 

package/2.guide/5.best-practices/.navigation.yml

@@ -0,0 +1,3 @@
+title: Best Practices
+titleTemplate: '%s · Best Practices'
+icon: i-lucide-square-check

package/2.guide/5.best-practices/hydration.md

@@ -0,0 +1,188 @@
+---
+navigation.title: 'Nuxt and hydration'
+title: Nuxt and hydration
+description: Why fixing hydration issues is important
+---
+
+When developing, you may face hydration issues. Don't ignore those warnings.
+
+# Why is it important to fix them?
+
+Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:
+
+## Performance Impact
+
+- **Increased time to interactive**: Hydration errors force Vue to re-render the entire component tree, which will increase the time for your Nuxt app to become interactive
+- **Poor user experience**: Users may see content flashing or unexpected layout shifts
+
+## Functionality Issues
+
+- **Broken interactivity**: Event listeners may not attach properly, leaving buttons and forms non-functional
+- **State inconsistencies**: Application state can become out of sync between what the user sees and what the application thinks is rendered
+- **SEO problems**: Search engines may index different content than what users actually see
+
+# How to detect them
+
+## Development Console Warnings
+
+Vue will log hydration mismatch warnings in the browser console during development:
+
+![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)
+
+# Common reasons
+
+## Browser-only APIs in Server Context
+
+**Problem**: Using browser-specific APIs during server-side rendering.
+
+```html
+<template>
+  <div>User preference: {{ userTheme }}</div>
+</template>
+
+<script setup>
+// This will cause hydration mismatch!
+// localStorage doesn't exist on the server!
+const userTheme = localStorage.getItem('theme') || 'light'
+</script>
+```
+
+**Solution**: You can use [`useCookie`](/docs/api/composables/use-cookie):
+
+```html
+<template>
+  <div>User preference: {{ userTheme }}</div>
+</template>
+
+<script setup>
+// This works on both server and client
+const userTheme = useCookie('theme', { default: () => 'light' })
+</script>
+```
+
+## Inconsistent Data
+
+**Problem**: Different data between server and client.
+
+```html
+<template>
+  <div>{{ Math.random() }}</div>
+</template>
+```
+
+**Solution**: Use SSR-friendly state:
+
+```html
+<template>
+  <div>{{ state }}</div>
+</template>
+
+<script setup>
+const state = useState('random', () => Math.random())
+</script>
+```
+
+## Conditional Rendering Based on Client State
+
+**Problem**: Using client-only conditions during SSR.
+
+```html
+<template>
+  <div v-if="window?.innerWidth > 768">
+    Desktop content
+  </div>
+</template>
+```
+
+**Solution**: Use media queries or handle it client-side:
+
+```html
+<template>
+  <div class="responsive-content">
+    <div class="hidden md:block">Desktop content</div>
+    <div class="md:hidden">Mobile content</div>
+  </div>
+</template>
+```
+
+## Third-party Libraries with Side Effects
+
+**Problem**: Libraries that modify the DOM or have browser dependencies (this happens a LOT with tag managers).
+
+```html
+<script setup>
+if (import.meta.client) {
+    const { default: SomeBrowserLibrary } = await import('browser-only-lib')
+    SomeBrowserLibrary.init()
+}
+</script>
+```
+
+**Solution**: Initialise libraries after hydration has completed:
+
+```html
+<script setup>
+onMounted(async () => {
+  const { default: SomeBrowserLibrary } = await import('browser-only-lib')
+  SomeBrowserLibrary.init()
+})
+</script>
+```
+
+## Dynamic Content Based on Time
+
+**Problem**: Content that changes based on current time.
+
+```html
+<template>
+  <div>{{ greeting }}</div>
+</template>
+
+<script setup>
+const hour = new Date().getHours()
+const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
+</script>
+```
+
+**Solution**: Use [`NuxtTime`](/docs/api/components/nuxt-time) component or handle it client-side:
+
+```html
+<template>
+  <div>
+    <NuxtTime :date="new Date()" format="HH:mm" />
+  </div>
+</template>
+```
+
+```html
+<template>
+  <div>
+    <ClientOnly>
+      {{ greeting }}
+      <template #fallback>
+        Hello!
+      </template>
+    </ClientOnly>
+  </div>
+</template>
+
+<script setup>
+const greeting = ref('Hello!')
+
+onMounted(() => {
+  const hour = new Date().getHours()
+  greeting.value = hour < 12 ? 'Good morning' : 'Good afternoon'
+})
+</script>
+```
+
+## In summary
+
+1. **Use SSR-friendly composables**: [`useFetch`](/docs/api/composables/use-fetch), [`useAsyncData`](/docs/api/composables/use-async-data), [`useState`](/docs/api/composables/use-state)
+2. **Wrap client-only code**: Use [`ClientOnly`](/docs/api/components/client-only) component for browser-specific content
+3. **Consistent data sources**: Ensure server and client uses the same data
+4. **Avoid side effects in setup**: Move browser-dependent code to `onMounted`
+
+::tip
+You can read the [Vue documentation on SSR hydration mismatch](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch) for a better understanding of hydration.
+::

package/2.guide/5.best-practices/performance.md

@@ -0,0 +1,305 @@
+---
+navigation.title: 'Nuxt Performance'
+title: Nuxt performance
+description: Best practices for improving performance of Nuxt apps.
+---
+
+Nuxt comes with built-in features designed to improve your application's performance and contribute to better [Core Web Vitals](https://web.dev/articles/vitals). There are also multiple Nuxt core modules that assist in improving performance in specific areas. This guide outlines best practices to optimize performance of your Nuxt application.
+
+## Built-in Features
+
+Nuxt offers several built-in features that help you optimize performance of your website. Understanding how these features work is crucial for achieving blazingly-fast performance.
+
+### Links
+
+[`<NuxtLink>`](/docs/api/components/nuxt-link) is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is internal or external and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
+
+```html
+<template>
+  <NuxtLink to="/about">About page</NuxtLink>
+</template>
+
+<!-- Which will render to with Vue Router & Smart Prefetching -->
+<a href="/about">About page</a>
+```
+
+Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link.
+
+You can also opt for prefetching on interaction instead:
+
+```ts
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      nuxtLink: {
+        prefetchOn: 'interaction',
+      },
+    }
+  }
+})
+```
+
+:read-more{title="NuxtLink" to="/docs/api/components/nuxt-link"}
+
+### Hybrid Rendering
+
+In more complex applications, we may need a full control over how our application is rendered to support cases where some pages could be generated at build time, while others should be client-side rendered
+
+Hybrid rendering allows different caching rules per route using Route Rules and decides how the server should respond to a new request on a given URL:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/': {
+      prerender: true
+    },
+    '/products/**': {
+      swr: 3600
+    },
+    '/blog': {
+      isr: 3600
+    },
+    '/admin/**': {
+      ssr: false
+    },
+  }
+})
+```
+
+Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using Nitro caching layer.
+
+:read-more{title="Hybrid rendering" to="/docs/guide/concepts/rendering#hybrid-rendering"}
+
+### Lazy Loading Components
+
+To dynamically import a component (also known as lazy-loading a component) all you need to do is add the Lazy prefix to the component's name. This is useful if the component is not always needed.
+
+```html
+<script setup lang="ts">
+const show = ref(false)
+</script>
+
+<template>
+  <div>
+    <h1>Mountains</h1>
+    <LazyMountainsList v-if="show" />
+    <button v-if="!show" @click="show = true">Show List</button>
+  </div>
+</template>
+```
+
+By using the Lazy prefix you can delay loading the component code until the right moment, which can be helpful for optimizing your JavaScript bundle size.
+
+:read-more{title="Lazy loading components" to="/docs/guide/directory-structure/components#dynamic-imports"}
+
+### Lazy Hydration
+
+It is not always necessary to hydrate (or make interactive) all the components of your site on the initial load. Using lazy hydration, you can control when components can have their code loaded, which can improve the time-to-interactive metric for your app. Nuxt allows you to control when components become interactive with lazy hydration (added in Nuxt v3.16).
+
+```html
+<template>
+  <div>
+    <LazyMyComponent hydrate-on-visible />
+  </div>
+</template>
+```
+
+To optimize your app, you may want to delay the hydration of some components until they're visible, or until the browser is done with more important tasks.
+
+:read-more{title="Lazy hydration" to="/docs/guide/directory-structure/components#delayed-or-lazy-hydration"}
+
+### Fetching data
+
+To avoid fetching same data twice (once on the server and once on client) Nuxt provides [`useFetch`](/docs/api/composables/use-fetch) and [`useAsyncData`](/docs/api/composables/use-async-data). They ensure that if an API call is made on the server, the data is forwarded to the client in the payload instead of being fetched again.
+
+:read-more{title="Data fetching" to="/docs/getting-started/data-fetching"}
+
+## Core Nuxt Modules
+
+Apart from Nuxt's built-in features, there are also core modules maintained by the Nuxt team which help improve performance even further. These modules help handle assets such as images, custom fonts, or third party scripts.
+
+### Images
+
+Unoptimized images can have a significant negative impact on your website performance, specifically the [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) score.
+
+In Nuxt we can use [Nuxt Image](https://image.nuxt.com/) module that is a plug-and-play image optimization for Nuxt apps. It allows resizing and transforming your images using built-in optimizer or your favorite images CDN.
+
+:video-accordion{title="Watch the video by LearnVue about Nuxt Image" videoId="_UBff2eqGY0"}
+
+[`<NuxtImg>`](/docs/api/components/nuxt-img) is a drop-in replacement for the native `<img>` tag that comes with following enhancements:
+
+* Uses built-in provider to optimize local and remote images
+* Converts `src` to provider optimized URLs with modern formats such as WebP or Avif
+* Automatically resizes images based on `width` and `height`
+* Generates responsive `sizes` when providing sizes option
+* Supports native `lazy loading` as well as other `<img>` attributes
+
+Images in your website can usually be separated by importance; the ones that are needed to be delivered first at initial load (i.e. `Largest Contentful Paint`), and the ones that can be loaded later or when specifically needed. For that, we could use the following optimizations:
+
+```html
+<template>
+  <!-- 🚨 Needs to be loaded ASAP -->
+  <NuxtImg
+    src="/hero-banner.jpg"
+    format="webp"
+    preload
+    loading="eager"
+    fetch-priority="high"
+    width="200"
+    height="100"
+  />
+
+  <!-- 🐌 Can be loaded later -->
+  <NuxtImg
+    src="/facebook-logo.jpg"
+    format="webp"
+    loading="lazy"
+    fetch-priority="low"
+    width="200"
+    height="100"
+  />
+</template>
+```
+
+:read-more{title="Nuxt Image" to="https://image.nuxt.com/usage/nuxt-img"}
+
+### Fonts
+
+[Nuxt Fonts](https://fonts.nuxt.com/) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.
+
+It includes built-in automatic self-hosting for any font file which means you can optimally load web fonts with reduced layout shift, thanks to the underlying package [fontaine](https://github.com/unjs/fontaine).
+
+:video-accordion{title="Watch the talk by Daniel Roe about the idea behind Nuxt Fonts" videoId="D3F683UViBY"}
+
+Nuxt Fonts processes all your CSS and does the following things automatically when it encounters a font-family declaration.
+
+1. **Resolves fonts** – Looks for font files in public/, then checks web providers like Google, Bunny, and Fontshare.
+2. **Generates @font-face rules** – Injects CSS rules to load fonts from the correct sources.
+3. **Proxies & caches fonts** – Rewrites URLs to `/_fonts`, downloads and caches fonts locally.
+4. **Creates fallback metrics** – Adjusts local system fonts to match web fonts, reducing layout shift ([CLS](https://web.dev/articles/cls)).
+5. **Includes fonts in build** – Bundles fonts with your project, hashing file names and setting long-lived cache headers.
+
+It supports multiple providers that are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own.
+
+### Scripts
+
+Third-party resources like analytics tools, video embeds, maps, and social media integrations enhance website functionality but can significantly degrade user experience and negatively impact [Interaction to Next Paint (INP)](https://web.dev/articles/inp) and Largest Contentful Paint (LCP) scores.
+
+[Nuxt Scripts](https://scripts.nuxt.com/) lets you load third-party scripts with better performance, privacy, security and DX.
+
+:video-accordion{title="Watch the video by Alex Lichter about Nuxt Scripts" videoId="sjMqUUvH9AE"}
+
+Nuxt Scripts provides an abstraction layer on top of third-party scripts, providing SSR support and type-safety and while still giving you full low-level control over how a script is loaded.
+
+```ts
+const { onLoaded, proxy } = useScriptGoogleAnalytics(
+  { 
+    id: 'G-1234567',
+    scriptOptions: {
+      trigger: 'manual',
+    },
+  },
+)
+// queue events to be sent when ga loads
+proxy.gtag('config', 'UA-123456789-1')
+// or wait until ga is loaded
+onLoaded((gtag) => {
+  // script loaded
+})
+```
+
+:read-more{title="Nuxt Scripts" to="https://scripts.nuxt.com/scripts"}
+
+## Profiling Tools
+
+To improve performance, we need to first know how to measure it, starting with measuring performance during development - on local environment, and then moving to auditing application that are deployed on production.
+
+### Nuxi Analyze
+
+[This](/docs/api/commands/analyze) command of `nuxi` allows to analyze the production bundle or your Nuxt application. It leverages `vite-bundle-visualizer` (similar to `webpack-bundle-analyzer`) to generate a visual representation of your application's bundle, making it easier to identify which components take up the most space.
+
+When you see a large block in the visualization, it often signals an opportunity for optimization—whether by splitting it into smaller parts, implementing lazy loading, or replacing it with a more efficient alternative, especially for third-party libraries.
+
+Large blocks containing multiple elements can often be reduced by importing only the necessary components rather than entire modules while large standalone blocks may be better suited for lazy loading rather than being included in the main bundle.
+
+### Nuxt DevTools
+
+The [Nuxt DevTools](https://devtools.nuxt.com/) gives you insights and transparency about your Nuxt App to identify performance gaps and seamlessly manage your app configurations.
+
+![Nuxt DevTools example](https://user-images.githubusercontent.com/11247099/217670806-fb39aeff-3881-44e5-b9c8-6c757f5925fc.png)
+
+It comes with several features we can use to measure performance of Nuxt apps:
+1. **Timeline** – Tracks time spent on rendering, updating, and initializing components to identify performance bottlenecks.  
+2. **Assets** – Displays file sizes (e.g., images) without transformations.  
+3. **Render Tree** – Shows connections between Vue components, scripts, and styles to optimize dynamic loading.  
+4. **Inspect** – Lists all files used in the Vue app with their size and evaluation time.
+
+### Chrome DevTools
+
+Chrome DevTools come with two useful tabs for measuring performance; `Performance` and `Lighthouse`.
+
+When you open the [Performance](https://developer.chrome.com/docs/devtools/performance/overview) panel, it instantly shows your local **Largest Contentful Paint (LCP)** and **Cumulative Layout Shift (CLS)** scores (good, needs improvement, or bad).  
+
+If you interact with the page, it also captures **Interaction to Next Paint (INP)**, giving you a full view of your Core Web Vitals based on your device and network.
+
+![Chrome DevTools Performance Panel](https://developer.chrome.com/static/docs/devtools/performance/image/cpu-throttling_856.png)
+
+[Lighthouse](https://developer.chrome.com/docs/devtools/lighthouse) audits performance, accessibility, SEO, progressive web apps, and best practices. It runs tests on your page and generates a report. Use failing audits as a guide to improve your site.
+
+![Lighthouse](https://developer.chrome.com/static/docs/lighthouse/images/lighthouse-overview_720.png)
+
+Each audit has a reference document explaining why the audit is important, as well as how to fix it.
+
+### PageSpeed Insights
+
+[PageSpeed Insights (PSI)](https://developers.google.com/speed/docs/insights/v5/about) reports on the user experience of a page on both mobile and desktop devices, and provides suggestions on how that page may be improved.
+
+It provides both lab and field data about a page. Lab data is useful for debugging issues, as it is collected in a controlled environment while field data is useful for capturing true, real-world user experience.
+
+### Web Page Test
+
+[WebPageTest](https://www.webpagetest.org/) is a web performance tool providing deep diagnostic information about how a page performs under a variety of conditions.
+
+Each test can be run from different locations around the world, on real browsers, over any number of customizable network conditions.
+
+## Common problems
+
+When building more complex Nuxt applications, you will probably encounter some of the problems listed below. Understanding these problems and fixing them will help you improve performance of your website.
+
+### Overusing plugins
+
+**Problem**: A large number of plugins can cause performance issues, especially if they require expensive computations or take too long to initialize. Since plugins run during the hydration phase, inefficient setups can block rendering and degrade the user experience.
+
+**Solution**: Inspect your plugins and see if some of them could be implemented rather as a composable or utility function instead.
+
+### Unused code / dependencies
+
+**Problem**: With the development of the project, there can be a case where there will be some unused code or a dependency. This additional functionality may not be used or needed while it will be increase the bundle size of our project.
+
+**Solution**: Inspect your `package.json` for unused dependencies and analyze your code for unused utils/composables/functions.
+
+### Not using Vue Performance tips
+
+**Problem**: [Vue documentation](https://vuejs.org/guide/best-practices/performance) lists several Performance improvements we can use in our Nuxt projects as well but as they are part of Vue documentation, developers tend to forget about it and focus on Nuxt specific improvements only - while Nuxt application is still a Vue project.
+
+**Solution**: Use concepts such as `shallowRef`, `v-memo`, `v-once`, etc to improve performance.
+
+### Not following patterns
+
+**Problem**: The more people are currently working on the project, the more difficult it will be to maintain the stable codebase. Developers have a tendency to introduce new concepts they've seen in another project which can cause conflicts and problems with performance.
+
+**Solution**: Establish rules and patterns in the project such as [Good practices and Design Patterns for Vue Composables](https://dev.to/jacobandrewsky/good-practices-and-design-patterns-for-vue-composables-24lk)
+
+### Trying to load everything at the same time
+
+**Problem**: When a page is loaded and it is not correctly instructed about the order of loading elements it will result in fetching everything at the same time - which can be slow and result in bad User Experience.
+
+**Solution**: Use concepts such as Progressive Enhancement where core webpage content is set first, then more nuanced and technically rigorous layers of presentation and features are added on top as the browser/internet connection allow.
+
+## Useful Resources
+
+To learn more about various techniques for improving performance, take a look at the following resources:
+
+1. [Apply instant loading with the PRPL pattern](https://web.dev/articles/apply-instant-loading-with-prpl)
+2. [Perceived performance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Performance/Perceived_performance)
+3. [Understanding Critical Rendering Path](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Critical_rendering_path)

package/2.guide/5.best-practices/plugins.md

@@ -0,0 +1,20 @@
+---
+navigation.title: 'Nuxt Plugins'
+title: Nuxt Plugins
+description: Best practices when using Nuxt plugins.
+---
+
+Plugins in Nuxt allow you to extend your application with additional functionality. However, improper use can lead to performance bottlenecks. This guide outlines best practices to optimize your Nuxt plugins.
+
+## Avoid costly plugin setup
+
+A large number of plugins can cause performance issues, especially if they require expensive computations or take too long to initialize. Since plugins run during the hydration phase, inefficient setups can block rendering and degrade the user experience.
+
+## Use Composition whenever possible
+
+Whenever possible, favor composition over plugins. Just like in Vue, many utilities and composables can be used directly without the need for a plugin. This keeps your project lightweight and improves maintainability.
+
+## If `async`, enable `parallel`
+
+By default, all plugins loads synchronously.
+When defining asynchronous plugins, setting `parallel: true` allows multiple plugins to load concurrently, improving performance by preventing blocking operations.

package/3.api/1.components/4.nuxt-link.md

@@ -226,7 +226,7 @@ export default defineNuxtConfig({
 
 When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/RouterLinkProps.html)
 
-- `to`: Any URL or a [route location object](https://router.vuejs.org/api/#RouteLocation) from Vue Router
+- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/RouteLocation.html) from Vue Router
 - `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-custom)
 - `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-exactActiveClass) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
 - `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-activeClass) on internal links. Defaults to Vue Router's default (`"router-link-active"`)

package/3.api/2.composables/use-response-header.md

@@ -15,7 +15,7 @@ This composable is available in Nuxt v3.14+.
 You can use the built-in [`useResponseHeader`](/docs/api/composables/use-response-header) composable to set any server response header within your pages, components, and plugins.
 
 ```ts
-// Set the a custom response header
+// Set a custom response header
 const header = useResponseHeader('X-My-Header');
 header.value = 'my-value';
 ```

package/3.api/2.composables/use-route.md

@@ -49,4 +49,4 @@ Apart from dynamic parameters and query parameters, `useRoute()` also provides t
 Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` in your template can trigger hydration issues because this will include the fragment on client but not the server.
 ::
 
-:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#RouteLocationNormalizedLoaded"}
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/RouteLocationNormalizedLoaded.html"}

package/3.api/3.utils/$fetch.md

@@ -20,7 +20,7 @@ Using `$fetch` in components without wrapping it with [`useAsyncData`](/docs/api
 
 ## Usage
 
-We recommend to use [`useFetch`](/docs/api/composables/use-fetch) or [`useAsyncData`](/docs/api/composables/use-async-data) + `$fetch` to prevent double data fetching when fetching the component data.
+We recommend using [`useFetch`](/docs/api/composables/use-fetch) or [`useAsyncData`](/docs/api/composables/use-async-data) + `$fetch` to prevent double data fetching when fetching the component data.
 
 ```vue [app.vue]
 <script setup lang="ts">

package/3.api/3.utils/define-nuxt-route-middleware.md

@@ -28,7 +28,7 @@ interface RouteMiddleware {
 
 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.
 
-Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/#RouteLocationNormalized)**.
+Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/type-aliases/RouteLocationNormalized.html)**.
 
 ## Examples
 

package/3.api/3.utils/on-before-route-leave.md

@@ -8,4 +8,4 @@ links:
     size: xs
 ---
 
-:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#onBeforeRouteLeave" title="Vue Router Docs" target="_blank"}
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/onBeforeRouteLeave.html" title="Vue Router Docs" target="_blank"}

package/3.api/3.utils/on-before-route-update.md

@@ -8,4 +8,4 @@ links:
     size: xs
 ---
 
-:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#onBeforeRouteUpdate" title="Vue Router Docs" target="_blank"}
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/functions/onBeforeRouteUpdate.html" title="Vue Router Docs" target="_blank"}

package/3.api/5.kit/1.modules.md

@@ -44,6 +44,12 @@ import type { ModuleDefinition, ModuleOptions, NuxtModule } from '@nuxt/schema'
 export function defineNuxtModule<TOptions extends ModuleOptions> (
   definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
 ): NuxtModule<TOptions, TOptions, false>
+
+export function defineNuxtModule<TOptions extends ModuleOptions> (): {
+  with: <TOptionsDefaults extends Partial<TOptions>> (
+    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>
+  ) => NuxtModule<TOptions, TOptionsDefaults, true>
+}
 ```
 
 ### Parameters
@@ -122,6 +128,49 @@ If the user tries to use your module with an incompatible Nuxt version, they wil
  - [nuxt] Nuxt version ^3.1.0 is required but currently using 3.0.0
 ```
 
+#### Type Safety for Resolved Options with `.with()`
+
+When you need type safety for your resolved/merged module options, you can use the `.with()` method. This enables TypeScript to properly infer the relationship between your module's defaults and the final resolved options that your setup function receives.
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+// Define your module options interface
+interface ModuleOptions {
+  apiKey: string
+  baseURL: string
+  timeout?: number
+  retries?: number
+}
+
+export default defineNuxtModule<ModuleOptions>().with({
+  meta: {
+    name: '@nuxtjs/my-api',
+    configKey: 'myApi'
+  },
+  defaults: {
+    baseURL: 'https://api.example.com',
+    timeout: 5000,
+    retries: 3
+  },
+  setup(resolvedOptions, nuxt) {
+    // resolvedOptions is properly typed as:
+    // {
+    //   apiKey: string          // Required, no default provided
+    //   baseURL: string         // Required, has default value
+    //   timeout: number         // Optional, has default value
+    //   retries: number         // Optional, has default value  
+    // }
+    
+    console.log(resolvedOptions.baseURL) // ✅ TypeScript knows this is always defined
+    console.log(resolvedOptions.timeout) // ✅ TypeScript knows this is always defined
+    console.log(resolvedOptions.retries) // ✅ TypeScript knows this is always defined
+  }
+})
+```
+
+Without using `.with()`, the `resolvedOptions` parameter would be typed as the raw `ModuleOptions` interface, where `timeout` and `retries` could be `undefined` even when defaults are provided. The `.with()` method enables TypeScript to understand that default values make those properties non-optional in the resolved options.
+
 ## `installModule`
 
 Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.

package/3.api/5.kit/10.templates.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Templates allows to generate extra files during development and build time. These files will be available in virtual filesystem and can be used in plugins, layouts, components, etc. `addTemplate` and `addTypeTemplate` allow you to add templates to the Nuxt application. `updateTemplates` allows you to regenerate templates that match the filter.
+Templates allow you to generate extra files during development and build time. These files will be available in virtual filesystem and can be used in plugins, layouts, components, etc. `addTemplate` and `addTypeTemplate` allow you to add templates to the Nuxt application. `updateTemplates` allows you to regenerate templates that match the filter.
 
 ## `addTemplate`
 

package/3.api/6.advanced/1.hooks.md

@@ -74,13 +74,13 @@ Hook                     | Arguments                  | Description
 `schema:resolved`        | `schema`                   | Allows extending resolved schema.
 `schema:beforeWrite`     | `schema`                   | Called before writing the given schema.
 `schema:written`         | -                          | Called after the schema is written.
-`vite:extend`            | `viteBuildContext`         | Allows to extend Vite default context.
-`vite:extendConfig`      | `viteInlineConfig, env`    | Allows to extend Vite default config.
-`vite:configResolved`    | `viteInlineConfig, env`    | Allows to read the resolved Vite config.
+`vite:extend`            | `viteBuildContext`         | Allows extending Vite default context.
+`vite:extendConfig`      | `viteInlineConfig, env`    | Allows extending Vite default config.
+`vite:configResolved`    | `viteInlineConfig, env`    | Allows reading the resolved Vite config.
 `vite:serverCreated`     | `viteServer, env`          | Called when the Vite server is created.
 `vite:compiled`          | -                          | Called after Vite server is compiled.
 `webpack:config`         | `webpackConfigs`           | Called before configuring the webpack compiler.
-`webpack:configResolved` | `webpackConfigs`           | Allows to read the resolved webpack config.
+`webpack:configResolved` | `webpackConfigs`           | Allows reading the resolved webpack config.
 `webpack:compile`        | `options`                  | Called right before compilation.
 `webpack:compiled`       | `options`                  | Called after resources are loaded.
 `webpack:change`         | `shortPath`                | Called on `change` on WebpackBar.

package/3.api/6.nuxt-config.md

@@ -37,13 +37,15 @@ your alias by prefixing it with `~`.
 
 **Example**:
 ```js
-export default {
+import { fileURLToPath } from "node:url";
+
+export default defineNuxtConfig({
   alias: {
     'images': fileURLToPath(new URL('./assets/images', import.meta.url)),
     'style': fileURLToPath(new URL('./assets/style', import.meta.url)),
     'data': fileURLToPath(new URL('./assets/other/data', import.meta.url))
   }
-}
+})
 ```
 
 ```html
@@ -814,7 +816,7 @@ export default defineNuxtConfig({
 
 ### `decorators`
 
-Enable to use experimental decorators in Nuxt and Nitro.
+Enable the use of experimental decorators in Nuxt and Nitro.
 
 - **Type**: `boolean`
 - **Default:** `false`
@@ -1466,7 +1468,7 @@ export default {
 
 Configuration for Nitro.
 
-**See**: [Nitro configuration docs](https://nitro.build/config/)
+**See**: [Nitro configuration docs](https://nitro.build/config)
 
 ### `routeRules`
 
@@ -1727,7 +1729,7 @@ Global route options applied to matching server routes.
 
 **Experimental**: This is an experimental feature and API may change in the future.
 
-**See**: [Nitro route rules documentation](https://nitro.build/config/#routerules)
+**See**: [Nitro route rules documentation](https://nitro.build/config#routerules)
 
 ## router
 

package/5.community/4.contribution.md

@@ -80,6 +80,24 @@ If we mark a PR as 'pending', that means we likely have another task to do in re
 
 We'll do our best to follow [our PR decision making flowchart](https://mermaid.live/view#pako:eNp9VE1v2kAQ_SsjXzBSEqlALlaUisSh0ACK2l4qcVm8Y9hi7672Iwly-O-ZtYPt5FAOCHbee_PmzdpVlCmOURLlhXrJ9sw4-JNuJNBnWs1UQafIQVjrERyWumAOv58-AJeXt29_0b7BXbWwwL0uRPa1vlZvcB_fF8oiMMmB2QM4BXkt3UoON7Lh3LWaDz2SVkK6QGt7DHvw0CKt5sxCKaQoWQEGtVHcZ04oGdw04LTVngW_LHOeFcURGGz97mw6PSv-iJdsi0UCA4nI7SfNwc3W3JZit3eQ1SZFDlKB15yswQ2MgbOjbYeatY3n8bcr-IWlekYYaJRcyB04I9gOB1CEfkF5dAVTzmFAtnqn4-bUYAiMMmHZgWhNPRhgus5mW2BATxq0NkIZ4Y4NbNjzE2ZchBzcHmGLe_ZMSKCcyRXyLrVFa_5n_PBK2xKy3kk9eOjULUdltk6C8kI-7NFDr8f4EVGDoqlp-wa4sJm3ltIMIuZ_mTQXJyTSkQZtunPqsKxShV9GKdkBYe1fHXjpbcjlvONlO9Kqx_M7YHmOmav_luxfE5zKwVs09hM5DLSupgYDlr5flDkwo7ykixKG-xDsUly1LZ-uY32dgDc7lG7YqwbNp0msJwmIUivjWFtfd-xRrEcJ7Omydz37qFplHOtxEp4GskI2qB5dRCWakglOz3oV8JuITJa4iRL6yZk5bKKNPBGOead-H2UWJc54vIiaW53SPgwrz4fIhVNm1bw76lfI6R2_MW21) when responding and reviewing to pull requests.
 
+### AI-Assisted Contributions
+
+We welcome the thoughtful use of AI tools when contributing to Nuxt, yet ask all contributors to follow [two core principles](https://roe.dev/blog/using-ai-in-open-source).
+
+#### Never let an LLM speak for you
+
+* All comments, issues, and pull request descriptions should be written in your own voice
+* We value clear, human communication over perfect grammar or spelling
+* Avoid copy-pasting AI-generated summaries that don't reflect your own understanding
+
+#### Never let an LLM think for you
+
+* Feel free to use AI tools to generate code or explore ideas
+* Only submit contributions you fully understand and can explain
+* Contributions should reflect your own reasoning and problem-solving
+
+Our aim is ensuring quality and maintaining the joy of collaborating and communicating with real people. If you have ideas for improving our policy on AI in the Nuxt community, we'd love to hear them! ❤️
+
 ### Create a Module
 
 If you've built something with Nuxt that's cool, why not [extract it into a module](/docs/guide/going-further/modules), so it can be shared with others? We have [many excellent modules already](/modules), but there's always room for more.

package/7.migration/6.pages-and-layouts.md

@@ -193,7 +193,7 @@ Most of the syntax and functionality are the same for the global [NuxtLink](/doc
 When migrating from Nuxt 2 to Nuxt 3, you will have to update how you programmatically navigate your users. In Nuxt 2, you had access to the underlying Vue Router with `this.$router`. In Nuxt 3, you can use the `navigateTo()` utility method which allows you to pass a route and parameters to Vue Router.
 
 ::warning
-Ensure to always `await` on [`navigateTo`](/docs/api/utils/navigate-to) or chain its result by returning from functions.
+Make sure to always `await` on [`navigateTo`](/docs/api/utils/navigate-to) or chain its result by returning from functions.
 ::
 
 ::code-group

package/7.migration/8.runtime-config.md

@@ -27,7 +27,7 @@ export default defineNuxtConfig({
     public: {
       apiBase: '/api'
     }
-  },
+  }
 })
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",