@nuxt/docs 3.17.7 → 3.18.1

package/3.api/3.utils/define-lazy-hydration-component.md

@@ -0,0 +1,261 @@
+---
+title: 'defineLazyHydrationComponent'
+description: 'Define a lazy hydration component with a specific strategy.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/components/plugins/lazy-hydration-macro-transform.ts
+    size: xs
+---
+
+`defineLazyHydrationComponent` is a compiler macro that helps you create a component with a specific lazy hydration strategy. Lazy hydration defers hydration until components become visible or until the browser has completed more critical tasks. This can significantly reduce the initial performance cost, especially for non-essential components.
+
+## Usage
+
+### Visibility Strategy
+
+Hydrates the component when it becomes visible in the viewport.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'visible',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- 
+      Hydration will be triggered when
+      the element(s) is 100px away from entering the viewport.
+    -->
+    <LazyHydrationMyComponent :hydrate-on-visible="{ rootMargin: '100px' }" />
+  </div>
+</template>
+```
+
+The `hydrateOnVisible` prop is optional. You can pass an object to customize the behavior of the `IntersectionObserver` under the hood.
+
+::read-more{to="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver" title="IntersectionObserver options"}
+Read more about the options for `hydrate-on-visible`.
+::
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-visible).
+::
+
+### Idle Strategy
+
+Hydrates the component when the browser is idle. This is suitable if you need the component to load as soon as possible, but not block the critical rendering path.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'idle',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- Hydration will be triggered when the browser is idle or after 2000ms. -->
+    <LazyHydrationMyComponent :hydrate-on-idle="2000" />
+  </div>
+</template>
+```
+
+The `hydrateOnIdle` prop is optional. You can pass a positive number to specify the maximum timeout.
+
+Idle strategy is for components that can be hydrated when the browser is idle.
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-idle).
+::
+
+### Interaction Strategy
+
+Hydrates the component after a specified interaction (e.g., click, mouseover).
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'interaction',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!--
+      Hydration will be triggered when
+      the element(s) is hovered over by the pointer.
+    -->
+    <LazyHydrationMyComponent hydrate-on-interaction="mouseover" />
+  </div>
+</template>
+```
+
+The `hydrateOnInteraction` prop is optional. If you do not pass an event or a list of events, it defaults to hydrating on `pointerenter`, `click`, and `focus`.
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-interaction).
+::
+
+### Media Query Strategy
+
+Hydrates the component when the window matches a media query.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'mediaQuery',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!--
+      Hydration will be triggered when
+      the window width is greater than or equal to 768px.
+    -->
+    <LazyHydrationMyComponent hydrate-on-media-query="(min-width: 768px)" />
+  </div>
+</template>
+```
+
+::note
+Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-media-query).
+::
+
+### Time Strategy
+
+Hydrates the component after a specified delay (in milliseconds).
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'time', 
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- Hydration is triggered after 1000ms. -->
+    <LazyHydrationMyComponent :hydrate-after="1000" />
+  </div>
+</template>
+```
+
+Time strategy is for components that can wait a specific amount of time.
+
+### If Strategy
+
+Hydrates the component based on a boolean condition.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'if',
+  () => import('./components/MyComponent.vue')
+)
+
+const isReady = ref(false)
+
+function myFunction() {
+  // Trigger custom hydration strategy...
+  isReady.value = true
+}
+</script>
+
+<template>
+  <div>
+    <!-- Hydration is triggered when isReady becomes true. -->
+    <LazyHydrationMyComponent :hydrate-when="isReady" />
+  </div>
+</template>
+```
+
+If strategy is best for components that might not always need to be hydrated.
+
+### Never Hydrate
+
+Never hydrates the component.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'never',
+  () => import('./components/MyComponent.vue')
+)
+</script>
+
+<template>
+  <div>
+    <!-- This component will never be hydrated by Vue. -->
+    <LazyHydrationMyComponent />
+  </div>
+</template>
+```
+
+### Listening to Hydration Events
+
+All delayed hydration components emit a `@hydrated` event when they are hydrated.
+
+```vue
+<script setup lang="ts">
+const LazyHydrationMyComponent = defineLazyHydrationComponent(
+  'visible',
+  () => import('./components/MyComponent.vue')
+)
+
+function onHydrate() {
+  console.log("Component has been hydrated!")
+}
+</script>
+
+<template>
+  <div>
+    <LazyHydrationMyComponent
+      :hydrate-on-visible="{ rootMargin: '100px' }"
+      @hydrated="onHydrated"
+    />
+  </div>
+</template>
+```
+
+## Parameters
+
+::warning
+To ensure that the compiler correctly recognizes this macro, avoid using external variables. The following approach will prevent the macro from being properly recognized:
+
+```vue
+<script setup lang="ts">
+const strategy = 'visible'
+const source = () => import('./components/MyComponent.vue')
+const LazyHydrationMyComponent = defineLazyHydrationComponent(strategy, source)
+</script>
+```
+::
+
+### `strategy`
+
+- **Type**: `'visible' | 'idle' | 'interaction' | 'mediaQuery' | 'if' | 'time' | 'never'`
+- **Required**: `true`
+
+| Strategy      | Description                                                    |
+|---------------|----------------------------------------------------------------|
+| `visible`     | Hydrates when the component becomes visible in the viewport.   |
+| `idle`        | Hydrates when the browser is idle or after a delay.            |
+| `interaction` | Hydrates upon user interaction (e.g., click, hover).           |
+| `mediaQuery`  | Hydrates when the specified media query condition is met.      |
+| `if`          | Hydrates when a specified boolean condition is met.            |
+| `time`        | Hydrates after a specified time delay.                         |
+| `never`       | Prevents Vue from hydrating the component.                     |
+
+### `source`
+
+- **Type**: `() => Promise<Component>`
+- **Required**: `true`

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/4.commands/init.md

@@ -38,6 +38,8 @@ Option | Default | Description
 `--gitInit` |  | Initialize git repository
 `--shell` |  | Start shell after installation in project directory
 `--packageManager` |  | Package manager choice (npm, pnpm, yarn, bun)
+`--modules` |  | Nuxt modules to install (comma separated without spaces)
+`--no-modules` |  | Skip module installation prompt
 <!--/init-opts-->
 
 ## Environment variables

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/5.kit/11.nitro.md

@@ -293,6 +293,53 @@ function addPrerenderRoutes (routes: string | string[]): void
 | ----------- | ------------------------------- | -------- | ---------------------------------------------- |
 | `routes`    | `string \| string[]`{lang="ts"} | `true`   | A route or an array of routes to prerender.    |
 
+## `addServerImports`
+
+Add imports to the server. It makes your imports available in Nitro without the need to import them manually.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, createResolver, addServerImports } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const names = [
+      'useStoryblok',
+      'useStoryblokApi',
+      'useStoryblokBridge',
+      'renderRichText',
+      'RichTextSchema'
+    ]
+
+    names.forEach((name) =>
+      addServerImports({ name, as: name, from: '@storyblok/vue' })
+    )
+  }
+})
+```
+
+### Type
+
+```ts
+function addServerImports (dirs: Import | Import[]): void
+```
+
+### Parameters
+
+`imports`: An object or an array of objects with the following properties:
+
+| Property           | Type                         | Required | Description                                                                                                     |
+| ------------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`                     | `true`   | Import name to be detected.                                                                                     |
+| `from`             | `string`                     | `true`   | Module specifier to import from.                                                                                |
+| `priority`         | `number`                     | `false`  | Priority of the import; if multiple imports have the same name, the one with the highest priority will be used. |
+| `disabled`         | `boolean`                    | `false`  | If this import is disabled.                                                                                     |
+| `meta`             | `Record<string, any>`        | `false`  | Metadata of the import.                                                                                         |
+| `type`             | `boolean`                    | `false`  | If this import is a pure type import.                                                                           |
+| `typeFrom`         | `string`                     | `false`  | Use this as the `from` value when generating type declarations.                                                 |
+| `as`               | `string`                     | `false`  | Import as this name.                                                                                            |
+
 ## `addServerImportsDir`
 
 Add a directory to be scanned for auto-imports by Nitro.

package/3.api/5.kit/4.autoimports.md

@@ -34,16 +34,16 @@ import { defineNuxtModule, addImports } from "@nuxt/kit";
 export default defineNuxtModule({
   setup(options, nuxt) {
     const names = [
-      "useStoryblok",
-      "useStoryblokApi",
-      "useStoryblokBridge",
-      "renderRichText",
-      "RichTextSchema"
-    ];
+      'useStoryblok',
+      'useStoryblokApi',
+      'useStoryblokBridge',
+      'renderRichText',
+      'RichTextSchema'
+    ]
 
     names.forEach((name) =>
-      addImports({ name, as: name, from: "@storyblok/vue" })
-    );
+      addImports({ name, as: name, from: '@storyblok/vue' })
+    )
   }
 })
 ```

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