@nuxt/docs 3.17.1 → 3.17.2

package/3.api/5.kit/6.context.md

@@ -8,64 +8,80 @@ links:
     size: xs
 ---
 
-Nuxt modules allow you to enhance Nuxt's capabilities. They offer a structured way to keep your code organized and modular. If you're looking to break down your module into smaller components, Nuxt offers the `useNuxt` and `tryUseNuxt` functions. These functions enable you to conveniently access the Nuxt instance from the context without having to pass it as argument.
+Nuxt modules allow you to enhance Nuxt's capabilities. They offer a structured way to keep your code organized and modular. If you're looking to break down your module into smaller components, Nuxt offers the `useNuxt` and `tryUseNuxt` functions. These functions enable you to conveniently access the Nuxt instance from the context without having to pass it as an argument.
 
 ::note
-When you're working with the `setup` function in Nuxt modules, Nuxt is already provided as the second argument. This means you can directly utilize it without needing to call `useNuxt()`. You can look at [Nuxt Site Config](https://github.com/harlan-zw/nuxt-site-config) as an example of usage.
+When you're working with the `setup` function in Nuxt modules, Nuxt is already provided as the second argument. This means you can access it directly without needing to call `useNuxt()`.
 ::
 
 ## `useNuxt`
 
 Get the Nuxt instance from the context. It will throw an error if Nuxt is not available.
 
-### Type
+### Usage
 
 ```ts
-function useNuxt(): Nuxt
+import { useNuxt } from '@nuxt/kit'
+
+const setupSomeFeature = () => {
+  const nuxt = useNuxt()
 
-interface Nuxt {
-  options: NuxtOptions
-  hooks: Hookable<NuxtHooks>
-  hook: Nuxt['hooks']['hook']
-  callHook: Nuxt['hooks']['callHook']
-  addHooks: Nuxt['hooks']['addHooks']
-  ready: () => Promise<void>
-  close: () => Promise<void>
-  server?: any
-  vfs: Record<string, string>
-  apps: Record<string, NuxtApp>
+  // You can now use the nuxt instance
+  console.log(nuxt.options)
 }
 ```
 
+### Type
+
+```ts twoslash
+// @errors: 2391
+import type { Nuxt } from '@nuxt/schema'
+// ---cut---
+function useNuxt(): Nuxt
+```
+
+### Return Value
+
+The `useNuxt` function returns the Nuxt instance, which contains all the options and methods available in Nuxt.
+
+| Property   | Type                                                                      | Description                                                                                               |
+| ---------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `options`  | `NuxtOptions`                                                             | The resolved Nuxt configuration.                                                                          |
+| `hooks`    | `Hookable<NuxtHooks>`                                                     | The Nuxt hook system. Allows registering and listening to lifecycle events.                               |
+| `hook`     | `(name: string, (...args: any[]) => Promise<void> \| void) => () => void` | Shortcut for `nuxt.hooks.hook`. Registers a single callback for a specific lifecycle hook.                |
+| `callHook` | `(name: string, ...args: any[]) => Promise<any>`                          | Shortcut for `nuxt.hooks.callHook`. Triggers a lifecycle hook manually and runs all registered callbacks. |
+| `addHooks` | `(configHooks: NestedHooks) => () => void`                                | Shortcut for `nuxt.hooks.addHooks`. Registers multiple hooks at once.                                     |
+
 ### Examples
 
 ::code-group
 
-```ts [setupTranspilation.ts]
-// https://github.com/Lexpeartha/nuxt-xstate/blob/main/src/parts/transpile.ts
+```ts twoslash [setupTranspilation.ts]
 import { useNuxt } from '@nuxt/kit'
 
 export const setupTranspilation = () => {
   const nuxt = useNuxt()
 
-  nuxt.options.build.transpile = nuxt.options.build.transpile || []
-
   if (nuxt.options.builder === '@nuxt/webpack-builder') {
-    nuxt.options.build.transpile.push(
-      'xstate',
-    )
+    nuxt.options.build.transpile ||= []
+    nuxt.options.build.transpile.push('xstate')
   }
 }
 ```
 
-```ts [module.ts]
-import { useNuxt } from '@nuxt/kit'
+```ts twoslash [module.ts]
+// @module: esnext
+// @filename: setupTranspilation.ts
+export const setupTranspilation = () => {}
+// @filename: module.ts
+import { defineNuxtModule } from '@nuxt/kit'
+// ---cut---
 import { setupTranspilation } from './setupTranspilation'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     setupTranspilation()
-  }
+  },
 })
 ```
 
@@ -75,55 +91,83 @@ export default defineNuxtModule({
 
 Get the Nuxt instance from the context. It will return `null` if Nuxt is not available.
 
-### Type
+### Usage
 
-```ts
-function tryUseNuxt(): Nuxt | null
+```ts twoslash
+import { tryUseNuxt } from '@nuxt/kit'
 
-interface Nuxt {
-  options: NuxtOptions
-  hooks: Hookable<NuxtHooks>
-  hook: Nuxt['hooks']['hook']
-  callHook: Nuxt['hooks']['callHook']
-  addHooks: Nuxt['hooks']['addHooks']
-  ready: () => Promise<void>
-  close: () => Promise<void>
-  server?: any
-  vfs: Record<string, string>
-  apps: Record<string, NuxtApp>
+function setupSomething () {
+  const nuxt = tryUseNuxt()
+
+  if (nuxt) {
+    // You can now use the nuxt instance
+    console.log(nuxt.options)
+  } else {
+    console.log('Nuxt is not available')
+  }
 }
 ```
 
+### Type
+
+```ts twoslash
+// @errors: 2391
+import type { Nuxt } from '@nuxt/schema'
+// ---cut---
+function tryUseNuxt(): Nuxt | null
+```
+
+### Return Value
+
+The `tryUseNuxt` function returns the Nuxt instance if available, or `null` if Nuxt is not available.
+
+The Nuxt instance as described in the `useNuxt` section.
+
 ### Examples
 
 ::code-group
 
-```ts [requireSiteConfig.ts]
-// https://github.com/harlan-zw/nuxt-site-config/blob/main/test/assertions.test.ts
+```ts twoslash [requireSiteConfig.ts]
+declare module '@nuxt/schema' {
+  interface NuxtOptions {
+    siteConfig: SiteConfig
+  }
+}
+// ---cut---
 import { tryUseNuxt } from '@nuxt/kit'
 
 interface SiteConfig {
-  title: string
+  title?: string
 }
 
 export const requireSiteConfig = (): SiteConfig => {
   const nuxt = tryUseNuxt()
   if (!nuxt) {
-    return { title: null }
+    return {}
   }
   return nuxt.options.siteConfig
 }
 ```
 
-```ts [module.ts]
-import { useNuxt } from '@nuxt/kit'
+```ts twoslash [module.ts]
+// @module: esnext
+// @filename: requireSiteConfig.ts
+interface SiteConfig {
+  title?: string
+}
+export const requireSiteConfig = (): SiteConfig => {
+ return {}
+}
+// @filename: module.ts
+// ---cut---
+import { defineNuxtModule, useNuxt } from '@nuxt/kit'
 import { requireSiteConfig } from './requireSiteConfig'
 
 export default defineNuxtModule({
-  setup(_, nuxt) {
+  setup (_, nuxt) {
     const config = requireSiteConfig()
     nuxt.options.app.head.title = config.title
-  }
+  },
 })
 ```
 

package/3.api/5.kit/7.pages.md

@@ -16,258 +16,149 @@ In Nuxt, routes are automatically generated based on the structure of the files
 Watch Vue School video about extendPages.
 ::
 
-### Type
-
-```ts
-function extendPages (callback: (pages: NuxtPage[]) => void): void
-
-type NuxtPage = {
-  name?: string
-  path: string
-  file?: string
-  meta?: Record<string, any>
-  alias?: string[] | string
-  redirect?: RouteLocationRaw
-  children?: NuxtPage[]
-}
-```
-
-### Parameters
-
-#### `callback`
+### Usage
 
-**Type**: `(pages: NuxtPage[]) => void`
-
-**Required**: `true`
-
-A function that will be called with the pages configuration. You can alter this array by adding, deleting, or modifying its elements. Note: You should modify the provided pages array directly, as changes made to a copied array will not be reflected in the configuration.
-
-### Examples
-
-```ts
-// https://github.com/nuxt-modules/prismic/blob/master/src/module.ts
+```ts twoslash
 import { createResolver, defineNuxtModule, extendPages } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options) {
-    const resolver = createResolver(import.meta.url)
+  setup (options) {
+    const { resolve } = createResolver(import.meta.url)
 
     extendPages((pages) => {
       pages.unshift({
         name: 'prismic-preview',
         path: '/preview',
-        file: resolver.resolve('runtime/preview.vue')
-       })
+        file: resolve('runtime/preview.vue'),
+      })
     })
-  }
+  },
 })
 ```
 
-## `extendRouteRules`
-
-Nuxt is powered by the [Nitro](https://nitro.unjs.io) server engine. With Nitro, you can incorporate high-level logic directly into your configuration, which is useful for actions like redirects, proxying, caching, and appending headers to routes. This configuration works by associating route patterns with specific route settings.
-
-::tip
-You can read more about Nitro route rules in the [Nitro documentation](https://nitro.unjs.io/guide/routing#route-rules).
-::
-
-::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
-Watch Vue School video about adding route rules and route middelwares.
-::
-
 ### Type
 
 ```ts
-function extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions): void
-
-interface NitroRouteConfig {
-  cache?: CacheOptions | false;
-  headers?: Record<string, string>;
-  redirect?: string | { to: string; statusCode?: HTTPStatusCode };
-  prerender?: boolean;
-  proxy?: string | ({ to: string } & ProxyOptions);
-  isr?: number | boolean;
-  cors?: boolean;
-  swr?: boolean | number;
-  static?: boolean | number;
-}
-
-interface ExtendRouteRulesOptions {
-  override?: boolean
-}
-
-interface CacheOptions {
-  swr?: boolean
-  name?: string
-  group?: string
-  integrity?: any
-  maxAge?: number
-  staleMaxAge?: number
-  base?: string
-  headersOnly?: boolean
-}
-
-// See https://www.jsdocs.io/package/h3#ProxyOptions
-interface ProxyOptions {
-  headers?: RequestHeaders | HeadersInit;
-  fetchOptions?: RequestInit & { duplex?: Duplex } & {
-    ignoreResponseError?: boolean;
-  };
-  fetch?: typeof fetch;
-  sendStream?: boolean;
-  streamRequest?: boolean;
-  cookieDomainRewrite?: string | Record<string, string>;
-  cookiePathRewrite?: string | Record<string, string>;
-  onResponse?: (event: H3Event, response: Response) => void;
-}
+function extendPages(callback: (pages: NuxtPage[]) => void): void
 ```
 
 ### Parameters
 
-#### `route`
-
-**Type**: `string`
+**callback**: A function that will be called with the pages configuration. You can alter this array by adding, deleting, or modifying its elements. Note: You should modify the provided pages array directly, as changes made to a copied array will not be reflected in the configuration.
 
-**Required**: `true`
+| Property   | Type                               | Required | Description                                                                                  |
+| ---------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `name`     | `string`                           | `false`  | The name of the route. Useful for programmatic navigation and identifying routes.            |
+| `path`     | `string`                           | `false`  | The route URL path. If not set, Nuxt will infer it from the file location.                   |
+| `file`     | `string`                           | `false`  | Path to the Vue file that should be used as the component for the route.                     |
+| `meta`     | `Record<string, any>`{lang="ts"}   | `false`  | Custom metadata for the route. Can be used in layouts, middlewares, or navigation guards.    |
+| `alias`    | `string[] \| string`{lang="ts"}    | `false`  | One or more alias paths for the route. Useful for supporting multiple URLs.                  |
+| `redirect` | `RouteLocationRaw`{lang="ts"}      | `false`  | Redirect rule for the route. Supports named routes, objects, or string paths.                |
+| `children` | `NuxtPage[]`{lang="ts"}            | `false`  | Nested child routes under this route for layout or view nesting.                             |
 
-A route pattern to match against.
-
-#### `rule`
-
-**Type**: `NitroRouteConfig`
-
-**Required**: `true`
-
-A route configuration to apply to the matched route.
+## `extendRouteRules`
 
-#### `options`
+Nuxt is powered by the [Nitro](https://nitro.unjs.io) server engine. With Nitro, you can incorporate high-level logic directly into your configuration, which is useful for actions like redirects, proxying, caching, and appending headers to routes. This configuration works by associating route patterns with specific route settings.
 
-**Type**: `ExtendRouteRulesOptions`
+::tip
+You can read more about Nitro route rules in the [Nitro documentation](https://nitro.unjs.io/guide/routing#route-rules).
+::
 
-**Default**: `{}`
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
+Watch Vue School video about adding route rules and route middelwares.
+::
 
-Options to pass to the route configuration. If `override` is set to `true`, it will override the existing route configuration.
+### Usage
 
-### Examples
-
-```ts
-// https://github.com/directus/website/blob/main/modules/redirects.ts
-import { createResolver, defineNuxtModule, extendRouteRules, extendPages } from '@nuxt/kit'
+```ts twoslash
+import { createResolver, defineNuxtModule, extendPages, extendRouteRules } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup(options) {
-    const resolver = createResolver(import.meta.url)
+  setup (options) {
+    const { resolve } = createResolver(import.meta.url)
 
     extendPages((pages) => {
       pages.unshift({
         name: 'preview-new',
         path: '/preview-new',
-        file: resolver.resolve('runtime/preview.vue')
-       })
+        file: resolve('runtime/preview.vue'),
+      })
     })
 
     extendRouteRules('/preview', {
       redirect: {
         to: '/preview-new',
-        statusCode: 302
-      }
+        statusCode: 302,
+      },
     })
 
     extendRouteRules('/preview-new', {
       cache: {
-        maxAge: 60 * 60 * 24 * 7
-      }
+        maxAge: 60 * 60 * 24 * 7,
+      },
     })
-  }
+  },
 })
 ```
 
-## `addRouteMiddleware`
-
-Registers route middlewares to be available for all routes or for specific routes.
-
-Route middlewares can be also defined in plugins via [`addRouteMiddleware`](/docs/api/utils/add-route-middleware) composable.
-
-::tip
-Read more about route middlewares in the [Route middleware documentation](/docs/getting-started/routing#route-middleware).
-::
-
-::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
-Watch Vue School video about adding route rules and route middelwares.
-::
-
 ### Type
 
 ```ts
-function addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options: AddRouteMiddlewareOptions): void
-
-type NuxtMiddleware = {
-  name: string
-  path: string
-  global?: boolean
-}
-
-interface AddRouteMiddlewareOptions {
-  override?: boolean
-  prepend?: boolean
-}
+function extendRouteRules(route: string, rule: NitroRouteConfig, options?: ExtendRouteRulesOptions): void
 ```
 
 ### Parameters
 
-#### `input`
-
-**Type**: `NuxtMiddleware | NuxtMiddleware[]`
-
-**Required**: `true`
-
-A middleware object or an array of middleware objects with the following properties:
-
-- `name` (required)
-
-  **Type**: `string`
-
-  Middleware name.
-
-- `path` (required)
-
-  **Type**: `string`
-
-  Path to the middleware.
+**route**: A route pattern to match against.\
+**rule**: A route rule configuration to apply to the matched route.
 
-- `global` (optional)
-
-  **Type**: `boolean`
-
-  If enabled, registers middleware to be available for all routes.
-
-#### `options`
+::tip
+About route rules configurations, you can get more detail in [Hybrid Rendering > Route Rules](/docs/guide/concepts/rendering#route-rules).
+::
 
-**Type**: `AddRouteMiddlewareOptions`
+**options**: A object to pass to the route configuration. If `override` is set to `true`, it will override the existing route configuration.
 
-**Default**: `{}`
+| Name       | Type      | Default | Description                                  |
+| ---------- | --------- | ------- | -------------------------------------------- |
+| `override` | `boolean` | `false` | Override route rule config, default is false |
 
-- `override` (optional)
+## `addRouteMiddleware`
 
-  **Type**: `boolean`
+Registers route middlewares to be available for all routes or for specific routes.
 
-  **Default**: `false`
+Route middlewares can be also defined in plugins via [`addRouteMiddleware`](/docs/api/utils/add-route-middleware) composable.
 
-  If enabled, overrides the existing middleware with the same name.
+::tip
+Read more about route middlewares in the [Route middleware documentation](/docs/getting-started/routing#route-middleware).
+::
 
-- `prepend` (optional)
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/adding-route-rules-and-route-middlewares?friend=nuxt" target="_blank"}
+Watch Vue School video about adding route rules and route middelwares.
+::
 
-  **Type**: `boolean`
+### Usage
 
-  **Default**: `false`
+::code-group
 
-  If enabled, prepends the middleware to the list of existing middleware.
+```ts twoslash [module.ts]
+import { addRouteMiddleware, createResolver, defineNuxtModule } from '@nuxt/kit'
 
-### Examples
+export default defineNuxtModule({
+  setup () {
+    const { resolve } = createResolver(import.meta.url)
 
-::code-group
+    addRouteMiddleware({
+      name: 'auth',
+      path: resolve('runtime/auth.ts'),
+      global: true,
+    }, { prepend: true })
+  },
+})
+```
 
-```ts [runtime/auth.ts]
+```ts twoslash [runtime/auth.ts]
+function isAuthenticated(): boolean { return false }
+// ---cut---
 export default defineNuxtRouteMiddleware((to, from) => {
   // isAuthenticated() is an example method verifying if a user is authenticated
   if (to.path !== '/login' && isAuthenticated() === false) {
@@ -276,20 +167,27 @@ export default defineNuxtRouteMiddleware((to, from) => {
 })
 ```
 
-```ts [module.ts]
-import { createResolver, defineNuxtModule, addRouteMiddleware } from '@nuxt/kit'
+::
 
-export default defineNuxtModule({
-  setup() {
-    const resolver = createResolver(import.meta.url)
+### Type
 
-    addRouteMiddleware({
-      name: 'auth',
-      path: resolver.resolve('runtime/auth.ts'),
-      global: true
-    }, { prepend: true })
-  }
-})
+```ts
+function addRouteMiddleware(input: NuxtMiddleware | NuxtMiddleware[], options?: AddRouteMiddlewareOptions): void
 ```
 
-::
+### Parameters
+
+**input**: A middleware object or an array of middleware objects with the following properties:
+
+| Property | Type      | Required | Description                                         |
+| -------- | --------- | -------- | --------------------------------------------------- |
+| `name`   | `string`  | `true`   | The name of the middleware.                         |
+| `path`   | `string`  | `true`   | The file path to the middleware.                    |
+| `global` | `boolean` | `false`  | If set to `true`, applies middleware to all routes. |
+
+**options**: An object with the following properties:
+
+| Property   | Type      | Default | Description                                                 |
+| ---------- | --------- | ------- | ----------------------------------------------------------- |
+| `override` | `boolean` | `false` | If `true`, replaces middleware with the same name.          |
+| `prepend`  | `boolean` | `false` | If `true`, prepends middleware before existing middlewares. |