@nuxt/docs 4.0.1 → 4.0.3

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

@@ -39,19 +39,19 @@ Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.
 ::code-group{sync="pm"}
 
 ```bash [npm]
-npm create nuxt <project-name>
+npm create nuxt@latest <project-name>
 ```
 
 ```bash [yarn]
-yarn create nuxt <project-name>
+yarn create nuxt@latest <project-name>
 ```
 
 ```bash [pnpm]
-pnpm create nuxt <project-name>
+pnpm create nuxt@latest <project-name>
 ```
 
 ```bash [bun]
-bun create nuxt <project-name>
+bun create nuxt@latest <project-name>
 ```
 
 ```bash [deno]

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

@@ -1072,7 +1072,16 @@ However, to take advantage of improved type checking, you can opt in to the new
    + "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
    ```
 
-4. **Configure Node.js TypeScript options** if needed:
+4. **Move all type augmentations into their appropriate context**:
+   * If you are augmenting types for the app context, move the files to the `app/` directory.
+   * If you are augmenting types for the server context, move the files to the `server/` directory.
+   * If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
+
+    ::warning
+    Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
+    ::
+
+5. **Configure Node.js TypeScript options** if needed:
    <!-- @case-police-ignore tsConfig -->
 
    ```ts
@@ -1094,7 +1103,7 @@ However, to take advantage of improved type checking, you can opt in to the new
    })
    ```
 
-5. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
+6. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
 
 The new configuration provides better type safety and IntelliSense for projects that opt in, while maintaining full backward compatibility for existing setups.
 

package/2.guide/1.concepts/10.nuxt-lifecycle.md

@@ -68,7 +68,7 @@ In Nuxt, there are three types of middleware:
 - **Named route middleware**
 - **Anonymous (or inline) route middleware**
 
-Nuxt automatically executes global middleware for first time enter to the application and every time before route navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
+Nuxt executes all global middleware on the initial page load (both on server and client) and then again before any client-side navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
 
 For details about each type and examples, see the [Middleware documentation](/docs/guide/directory-structure/middleware).
 

package/2.guide/1.concepts/8.typescript.md

@@ -108,6 +108,20 @@ Each of these files is configured to reference the appropriate dependencies and
 The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.
 ::
 
+### Augmenting Types with Project References
+
+Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they are properly recognized.
+
+For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory.
+
+Similarly:
+- For the `server` context, place the augmentation file in the `server/` directory.
+- For types that are **shared between the app and server**, place the file in the `shared/` directory.
+
+::warning
+Augmenting types outside of these directories will not be recognized by TypeScript.
+::
+
 ## Strict Checks
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.

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/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/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-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/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/6.nuxt-config.md

@@ -19,7 +19,7 @@ You can improve your DX by defining additional aliases to access custom director
   "@@": "/<rootDir>",
   "#shared": "/<rootDir>/shared",
   "assets": "/<srcDir>/assets",
-  "public": "/<srcDir>/public",
+  "public": "/<rootDir>/public",
   "#build": "/<rootDir>/.nuxt",
   "#internal/nuxt/paths": "/<rootDir>/.nuxt/paths.mjs"
 }

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/package.json

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