@nuxt/docs 4.0.1 → 4.0.2

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/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/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.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",