@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e

package/4.api/3.utils/define-route-rules.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-::read-more{to="/docs/4.x/guide/going-further/experimental-features#inlinerouterules" icon="i-lucide-star"}
+::read-more{to="/docs/guide/going-further/experimental-features#inlinerouterules" icon="i-lucide-star"}
 This feature is experimental and in order to use it you must enable the `experimental.inlineRouteRules` option in your `nuxt.config`.
 ::
 
@@ -37,7 +37,7 @@ export default defineNuxtConfig({
 ```
 
 ::note
-When running [`nuxt build`](/docs/4.x/api/commands/build), the home page will be pre-rendered in `.output/public/index.html` and statically served.
+When running [`nuxt build`](/docs/api/commands/build), the home page will be pre-rendered in `.output/public/index.html` and statically served.
 ::
 
 ## Notes
@@ -48,8 +48,8 @@ When running [`nuxt build`](/docs/4.x/api/commands/build), the home page will be
 
 If a page path cannot be converted to an equivalent route rule pattern (for example, a param with a regular expression like `/:id(\d+)`, a partial segment like `/prefix-:id`, or a repeatable param like `/:slug+`), the rules for that page are **not** applied and Nuxt warns during build. In that case, define the rules explicitly in `nitro.routeRules` in your `nuxt.config`.
 
-For more control, such as if you are using a custom `path` or `alias` set in the page's [`definePageMeta`](/docs/4.x/api/utils/define-page-meta), you should set `routeRules` directly within your `nuxt.config`.
+For more control, such as if you are using a custom `path` or `alias` set in the page's [`definePageMeta`](/docs/api/utils/define-page-meta), you should set `routeRules` directly within your `nuxt.config`.
 
-::read-more{to="/docs/4.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
+::read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
 Read more about the `routeRules`.
 ::

package/4.api/3.utils/define-use-async-data-addon.md

@@ -0,0 +1,57 @@
+---
+title: 'defineUseAsyncDataAddon'
+description: Define a reusable addon that extends composables created with createUseAsyncData.
+minimalVersion: "4.6"
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/addons.ts
+    size: xs
+---
+
+`defineUseAsyncDataAddon` defines a reusable extension for `useAsyncData` composables created with [`createUseAsyncData`](/docs/api/composables/create-use-async-data).
+
+An addon can declare custom call-site options, wrap the handler with middleware, attach custom reactive logic or extend the returned object.
+
+:read-more{to="/docs/api/utils/define-use-fetch-addon" title="defineUseFetchAddon: Addons for useAsyncData work the same way as useFetch addons"}
+
+## Usage
+
+For example, an addon adding a `pollEvery` option that refreshes the data on an interval:
+
+```ts [app/composables/usePolledAsyncData.ts]
+const polling = defineUseAsyncDataAddon({
+  setup: (options: UseAsyncDataAddonOptions<{ pollEvery?: number }>) => {
+    if (import.meta.server || !options.pollEvery) { return }
+    return (asyncData) => {
+      const interval = setInterval(() => asyncData.refresh(), options.pollEvery)
+      onScopeDispose(() => clearInterval(interval))
+    }
+  },
+})
+
+export const usePolledAsyncData = createUseAsyncData({ addons: [polling] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// refreshes the data every 30 seconds
+const { data } = await usePolledAsyncData(
+  'mountains',
+  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  { pollEvery: 30_000 },
+)
+</script>
+```
+
+::note
+Addons run in the order of the `addons` array, with middleware from the first addon as the outermost wrapper. Listing the same addon object more than once runs it only once.
+::
+
+## Type
+
+```ts [Signature]
+function defineUseAsyncDataAddon<Opts extends Record<string, any> = {}, Ext = {}> (addon: {
+  setup: (options: UseAsyncDataAddonOptions<Opts>) => ((asyncData: AsyncDataAddonInstance) => Ext | void) | void
+}): UseAsyncDataAddon<Opts, Ext>
+```

package/4.api/3.utils/define-use-fetch-addon.md

@@ -0,0 +1,168 @@
+---
+title: 'defineUseFetchAddon'
+description: Define a reusable addon that extends composables created with createUseFetch.
+minimalVersion: "4.6"
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/addons.ts
+    size: xs
+---
+
+`defineUseFetchAddon` defines a reusable extension for `useFetch` composables created with [`createUseFetch`](/docs/api/composables/create-use-fetch).
+
+An addon can declare custom call-site options, wrap the handler with middleware, attach custom reactive logic or extend the returned object.
+
+## Usage
+
+Pass addons to `createUseFetch` via the `addons` array.
+
+This addon attaches custom logic: a watcher that refreshes the data whenever the window regains focus and gates it behind a custom `refreshOnFocus` option:
+
+```ts [app/composables/useCustomFetch.ts]
+const refreshOnFocus = defineUseFetchAddon({
+  // augment the call-site options for the custom useFetch instance 👇
+  setup: (options: UseFetchAddonOptions<{ refreshOnFocus?: boolean }>) => {
+    // 👈 run code *before* calling `useAsyncData` in `useFetch`
+    if (import.meta.server || !options.refreshOnFocus) { return }
+
+    return (asyncData) => {
+      // 👈 run code *after* calling `useAsyncData` in `useFetch`
+      const focused = useWindowFocus()
+      watch(focused, (focused) => {
+        if (focused) { asyncData.refresh() }
+      })
+
+      return { focused } // 👈 extend the returned object with a new property
+    }
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [refreshOnFocus] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+const { data } = await useCustomFetch('/some-endpoint', { refreshOnFocus: true })
+</script>
+```
+
+The addon's `setup` function runs on every call of the composable, and receives the merged options (factory defaults plus caller options).
+
+::note
+Addons run in the order of the `addons` array, with middleware from the first addon as the outermost wrapper. Listing the same addon object more than once runs it only once.
+::
+
+## Custom Options
+
+Declare custom options by annotating the `setup` `options` parameter with `UseFetchAddonOptions<{ ... }>`. The options become part of the created composable's signature, fully typed for callers:
+
+```ts [app/composables/useCustomFetch.ts]
+const auth = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ auth?: MaybeRefOrGetter<boolean> }>) => {
+    const { token } = useTokenStore()
+    options.auth ??= true
+    options.onRequest.push(({ options: fetchOptions }) => {
+      if (!toValue(options.auth)) { return }
+      fetchOptions.headers.set('Authorization', `Bearer ${token.value}`)
+    })
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [auth] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `auth` is typed
+const { data } = await useCustomFetch('/public-endpoint', { auth: false })
+</script>
+```
+
+Custom options stay in the merged options object, so they are also passed to `$fetch` along with the request options, which ignores keys it does not recognise.
+
+## Extending the Return Value
+
+If `setup` returns a function, that function is called with the async data instance. Any object it returns is merged into the composable's return value:
+
+```ts
+const timestamps = defineUseFetchAddon({
+  setup: () => {
+    const refreshedAt = ref<Date>()
+
+    return (asyncData) => {
+      watch(asyncData.status, (status) => {
+        if (status === 'success') { refreshedAt.value = new Date() }
+      }, { immediate: true })
+
+      return { refreshedAt: readonly(refreshedAt) }
+    }
+  },
+})
+
+export const useCustomFetch = createUseFetch({ addons: [timestamps] })
+```
+
+```vue [app/pages/index.vue]
+<script setup lang="ts">
+// `refreshedAt` is typed
+const { data, refreshedAt } = await useCustomFetch('/modules')
+</script>
+```
+
+## Middleware
+
+Middleware wraps the execution of the request handler. Call `next()` to continue the chain (and get the resolved data), or throw to abort. Middleware from the first addon is the outermost wrapper:
+
+```ts
+const minDuration = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ minDuration?: number }>) => {
+    options.middleware.push(async (next) => {
+      const [result] = await Promise.all([
+        next(),
+        new Promise(resolve => setTimeout(resolve, toValue(options.minDuration) ?? 300)),
+      ])
+      return result
+    })
+  },
+})
+```
+
+## Contributing to the Auto-Generated Key
+
+Custom options are **not** part of the auto-generated key by default. If a custom option affects the response, provide a `key` resolver so calls with different values do not share a cached entry. Return a serializable value, or `undefined` to contribute nothing:
+
+```ts
+const scoped = defineUseFetchAddon({
+  setup: (options: UseFetchAddonOptions<{ scope?: string }>) => {
+    options.scope ??= 'default'
+    // ...
+  },
+  key: options => toValue(options.scope),
+})
+```
+
+::warning
+Declare `setup` before `key`. TypeScript infers the custom options from the `setup` parameter annotation, and a `key` resolver written before a `setup` that returns an extension function is checked first and typed with empty options.
+::
+
+## Wrapping `then`, `catch` and `finally`
+
+As an advanced escape hatch, the extension object may include `then`, `catch` or `finally` functions. These are not merged into the instance. Instead they wrap the corresponding method of the awaitable promise, receiving the original method as their first argument.
+
+::note
+When several addons wrap the same method, the wrappers are composed in the order of the `addons` array: the first addon's wrapper wraps all the following ones, just as its middleware would.
+::
+
+## Type
+
+```ts [Signature]
+function defineUseFetchAddon<Opts extends Record<string, any> = {}, Ext = {}> (addon: {
+  setup: (options: UseFetchAddonOptions<Opts>) => ((asyncData: AsyncDataAddonInstance) => Ext | void) | void
+  key?: (options: UseFetchAddonOptions<Opts>) => SerializableValue
+}): UseFetchAddon<Opts, Ext>
+```
+
+::note
+`middleware`, `onRequest`, `onRequestError`, `onResponse` and `onResponseError` are always normalized to arrays, so interceptors from the caller and from other addons are preserved.
+::

package/4.api/3.utils/navigate-to.md

@@ -10,7 +10,7 @@ links:
 
 ## Usage
 
-`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.
+`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.
 
 ::warning
 Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
@@ -41,6 +41,10 @@ await navigateTo({
 </script>
 ```
 
+::note
+Calling `navigateTo` does not stop execution of the rest of your `<script setup>` code. If you want a successful navigation to return early from `setup()`, enable [`experimental.navigateToEarlyReturn`](/docs/guide/going-further/experimental-features#navigatetoearlyreturn).
+::
+
 ### Within Route Middleware
 
 ```ts
@@ -68,7 +72,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
 
 In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior.
 
-:read-more{to="/docs/4.x/directory-structure/app/middleware"}
+:read-more{to="/docs/directory-structure/app/middleware"}
 
 ### Navigating to an External URL
 

package/4.api/3.utils/prefetch-components.md

@@ -20,7 +20,7 @@ await prefetchComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
 ```
 
 ::note
-Current implementation behaves exactly the same as [`preloadComponents`](/docs/4.x/api/utils/preload-components) by preloading components instead of just prefetching we are working to improve this behavior.
+Current implementation behaves exactly the same as [`preloadComponents`](/docs/api/utils/preload-components) by preloading components instead of just prefetching we are working to improve this behavior.
 ::
 
 ::note

package/4.api/3.utils/preload-route-components.md

@@ -14,7 +14,7 @@ Preloading routes loads the components of a given route that the user might navi
 Nuxt already automatically preloads the necessary routes if you're using the `NuxtLink` component.
 ::
 
-:read-more{to="/docs/4.x/api/components/nuxt-link"}
+:read-more{to="/docs/api/components/nuxt-link"}
 
 ## Example
 
@@ -34,7 +34,7 @@ const submit = async () => {
 }
 ```
 
-:read-more{to="/docs/4.x/api/utils/navigate-to"}
+:read-more{to="/docs/api/utils/navigate-to"}
 
 ::note
 On server, `preloadRouteComponents` will have no effect.

package/4.api/3.utils/prerender-routes.md

@@ -1,6 +1,6 @@
 ---
 title: 'prerenderRoutes'
-description: prerenderRoutes hints to Nitro to prerender an additional route.
+description: prerenderRoutes hints that an additional route should be prerendered.
 minimalVersion: "3.8"
 links:
   - label: Source
@@ -9,10 +9,10 @@ links:
     size: xs
 ---
 
-When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.
+When prerendering, you can hint that additional paths should be prerendered, even if their URLs do not show up in the HTML of the generated page. Nuxt collects the hints and passes them to your server builder's prerenderer (Nitro by default).
 
 ::important
-`prerenderRoutes` can only be called within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
+`prerenderRoutes` can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
 ::
 
 ::note

package/4.api/3.utils/refresh-cookie.md

@@ -34,7 +34,7 @@ const loggedIn = computed(() => !!tokenCookie.value)
 </script>
 ```
 
-::note{to="/docs/4.x/guide/going-further/experimental-features#cookiestore"}
+::note{to="/docs/guide/going-further/experimental-features#cookiestore"}
 Since [Nuxt v3.12.0](https://github.com/nuxt/nuxt/releases/tag/v3.12.0), the experimental `cookieStore` option is enabled by default. It automatically refreshes the `useCookie` value when cookies change in the browser.
 ::
 

package/4.api/3.utils/refresh-nuxt-data.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`refreshNuxtData` is used to refetch all or specific `asyncData` instances, including those from [`useAsyncData`](/docs/4.x/api/composables/use-async-data), [`useLazyAsyncData`](/docs/4.x/api/composables/use-lazy-async-data), [`useFetch`](/docs/4.x/api/composables/use-fetch), and [`useLazyFetch`](/docs/4.x/api/composables/use-lazy-fetch).  
+`refreshNuxtData` is used to refetch all or specific `asyncData` instances, including those from [`useAsyncData`](/docs/api/composables/use-async-data), [`useLazyAsyncData`](/docs/api/composables/use-lazy-async-data), [`useFetch`](/docs/api/composables/use-fetch), and [`useLazyFetch`](/docs/api/composables/use-lazy-fetch).  
 
 ::note
 If your component is cached by `<KeepAlive>` and enters a deactivated state, the `asyncData` inside the component will still be refetched until the component is unmounted.
@@ -22,7 +22,7 @@ export function refreshNuxtData (keys?: string | string[])
 
 ## Parameters
 
-* `keys`: A single string or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) keys are re-fetched when no `keys` are explicitly specified.
+* `keys`: A single string or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) keys are re-fetched when no `keys` are explicitly specified.
 
 ## Return Values
 
@@ -93,4 +93,4 @@ async function refresh () {
 If you have access to the `asyncData` instance, it is recommended to use its `refresh` or `execute` method as the preferred way to refetch the data.
 ::
 
-:read-more{to="/docs/4.x/getting-started/data-fetching"}
+:read-more{to="/docs/getting-started/data-fetching"}

package/4.api/3.utils/reload-nuxt-app.md

@@ -15,7 +15,7 @@ links:
 
 By default, it will also save the current `state` of your app (that is, any state you could access with `useState`).
 
-::read-more{to="/docs/4.x/guide/going-further/experimental-features#restorestate" icon="i-lucide-star"}
+::read-more{to="/docs/guide/going-further/experimental-features#restorestate" icon="i-lucide-star"}
 You can enable experimental restoration of this state by enabling the `experimental.restoreState` option in your `nuxt.config` file.
 ::
 

package/4.api/3.utils/set-page-layout.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::important
-`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
+`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
 ::
 
 ```ts [app/middleware/custom-layout.ts]

package/4.api/3.utils/set-response-status.md

@@ -13,7 +13,7 @@ Nuxt provides composables and utilities for first-class server-side-rendering su
 `setResponseStatus` sets the status (and optionally the statusText) of the response.
 
 ::important
-`setResponseStatus` can only be called in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
+`setResponseStatus` can only be called in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
 ::
 
 ```ts
@@ -33,4 +33,4 @@ if (event) {
 In the browser, `setResponseStatus` will have no effect.
 ::
 
-:read-more{to="/docs/4.x/getting-started/error-handling"}
+:read-more{to="/docs/getting-started/error-handling"}

package/4.api/3.utils/show-error.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.
+Within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.
 
 **Parameters:**
 
@@ -22,10 +22,10 @@ showError({
 })
 ```
 
-The error is set in the state using [`useError()`](/docs/4.x/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
+The error is set in the state using [`useError()`](/docs/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
 
 ::tip
 `showError` calls the `app:error` hook.
 ::
 
-:read-more{to="/docs/4.x/getting-started/error-handling"}
+:read-more{to="/docs/getting-started/error-handling"}

package/4.api/3.utils/update-app-config.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::note
-Updates the [`app.config`](/docs/4.x/directory-structure/app/app-config) using deep assignment. Existing (nested) properties will be preserved.
+Updates the [`app.config`](/docs/directory-structure/app/app-config) using deep assignment. Existing (nested) properties will be preserved.
 ::
 
 ## Usage
@@ -25,4 +25,4 @@ updateAppConfig(newAppConfig)
 console.log(appConfig) // { foo: 'baz' }
 ```
 
-:read-more{to="/docs/4.x/directory-structure/app/app-config"}
+:read-more{to="/docs/directory-structure/app/app-config"}

package/4.api/4.commands/README.md

@@ -0,0 +1,9 @@
+---
+navigation: false
+---
+
+# Nuxt CLI Commands
+
+The Nuxt CLI command reference now lives in the `docs/` directory of <https://github.com/nuxt/cli>, which is the source of truth for these pages.
+
+Editing files in this directory has no effect on the website. Please open your pull request against `nuxt/cli` instead.

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

@@ -62,7 +62,7 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `defaults`           | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                                                             | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.                                                                                         |
 | `schema`             | `T`                                                                                                               | `false`  | Schema for the module options. If provided, options will be applied to the schema.                                                                                                                                 |
 | `hooks`              | `Partial<NuxtHooks>`{lang="ts"}                                                                                   | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                                                                                                                              |
-| `moduleDependencies` | `Record<string, ModuleDependency> \| ((nuxt: Nuxt) => Record<string, ModuleDependency>)`{lang="ts"}               | `false`  | Dependencies on other modules with version constraints and configuration. Can be an object or a function that receives the Nuxt instance. See [example](/docs/4.x/api/kit/modules#specifying-module-dependencies). |
+| `moduleDependencies` | `Record<string, ModuleDependency> \| ((nuxt: Nuxt) => Record<string, ModuleDependency>)`{lang="ts"}               | `false`  | Dependencies on other modules with version constraints and configuration. Can be an object or a function that receives the Nuxt instance. See [example](/docs/api/kit/modules#specifying-module-dependencies). |
 | `onInstall`          | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                                                                      | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined.                                                                                                   |
 | `onUpgrade`          | `(nuxt: Nuxt, options: T, previousVersion: string) => Awaitable<void>`{lang="ts"}                                 | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined.                                                                                       |
 | `setup`              | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.                                                                                                                               |
@@ -113,7 +113,7 @@ export default defineNuxtConfig({
 ```
 
 ::tip
-This is particularly useful when you want to disable modules inherited from [Nuxt layers](/docs/4.x/guide/going-further/layers#disabling-modules-from-layers).
+This is particularly useful when you want to disable modules inherited from [Nuxt layers](/docs/guide/going-further/layers#disabling-modules-from-layers).
 ::
 
 #### Defining Module Compatibility Requirements
@@ -337,7 +337,7 @@ export default defineNuxtModule({
 ## `installModule`
 
 ::callout{type="warning"}
-**Deprecated:** Use the [`moduleDependencies`](/docs/4.x/api/kit/modules#specifying-module-dependencies) option in `defineNuxtModule` instead. The `installModule` function will be removed (or may become non-blocking) in a future version.
+**Deprecated:** Use the [`moduleDependencies`](/docs/api/kit/modules#specifying-module-dependencies) option in `defineNuxtModule` instead. The `installModule` function will be removed (or may become non-blocking) in a future version.
 ::
 
 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/4.api/5.kit/10.runtime-config.md

@@ -10,7 +10,7 @@ links:
 
 ## `useRuntimeConfig`
 
-At build-time, it is possible to access the resolved Nuxt [runtime config](/docs/4.x/guide/going-further/runtime-config).
+At build-time, it is possible to access the resolved Nuxt [runtime config](/docs/guide/going-further/runtime-config).
 
 ### Type
 

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

@@ -56,6 +56,7 @@ function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate
 | `options`     | `Options`                                                 | `false`  | Options to pass to the template.                                                                                                                                                 |
 | `getContents` | `(data: Options) => string \| Promise<string>`{lang="ts"} | `false`  | A function that will be called with the `options` object. It should return a string or a promise that resolves to a string. If `src` is provided, this function will be ignored. |
 | `write`       | `boolean`                                                 | `false`  | If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.                                         |
+| `dependsOn`   | `Array<'pages' \| 'plugins'> \| ((change: { event, path }, ctx: { nuxt, app, options }) => boolean)`{lang="ts"} | `false`  | The watched inputs the output of the template can depend on, beyond `nuxt.options` and the resolved structure of the app. Set to `[]` if the template never reads the contents of a watched file, so that Nuxt can skip recompiling it in dev mode when a file changes without any file being added or removed. List well-known keys if the template reads those sources, or pass a function to decide per change. A template that declares nothing is regenerated on every change. |
 
 ### Example
 
@@ -82,6 +83,47 @@ export default defineNuxtModule({
 })
 ```
 
+#### Skipping Regeneration in Development
+
+By default, Nuxt recompiles a template on every watched file event because it cannot know what
+the template reads. If your template is built only from configuration and from which files exist,
+declare that so Nuxt can leave it alone when a file is edited:
+
+```ts twoslash [module.ts]
+import { addTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    addTemplate({
+      filename: 'my-module/config.mjs',
+      dependsOn: [],
+      getContents: () => 'export default ' + JSON.stringify(options),
+    })
+  },
+})
+```
+
+If the template reads well-known sources, declare them by key:
+
+```ts
+addTemplate({
+  filename: 'my-module/routes.mjs',
+  dependsOn: ['pages'],
+  getContents: ({ app }) => generateRoutes(app.pages),
+})
+```
+
+And if it reads files Nuxt doesn't know about, say a set of YAML files you scan yourself, pass a
+function instead:
+
+```ts
+addTemplate({
+  filename: 'my-module/content.mjs',
+  dependsOn: ({ path }) => path.endsWith('.yaml'),
+  getContents: () => generateContents(),
+})
+```
+
 In the module above, we generate a virtual file named `meta.config.mjs`. In the runtime plugin, we can import it using the `#build` alias:
 
 ```ts [runtime/plugin.ts]