@nuxt/docs 0.0.0 → 3.17.0

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

@@ -0,0 +1,295 @@
+---
+title: Pages
+description: Nuxt Kit provides a set of utilities to help you create and use pages. You can use these utilities to manipulate the pages configuration or to define route rules.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/pages.ts
+    size: xs
+---
+
+## `extendPages`
+
+In Nuxt, routes are automatically generated based on the structure of the files in the `pages` directory. However, there may be scenarios where you'd want to customize these routes. For instance, you might need to add a route for a dynamic page not generated by Nuxt, remove an existing route, or modify the configuration of a route. For such customizations, Nuxt offers the `extendPages` feature, which allows you to extend and alter the pages configuration.
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/extend-and-alter-nuxt-pages?friend=nuxt" target="_blank"}
+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`
+
+**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
+import { createResolver, defineNuxtModule, extendPages } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+
+    extendPages((pages) => {
+      pages.unshift({
+        name: 'prismic-preview',
+        path: '/preview',
+        file: resolver.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;
+}
+```
+
+### Parameters
+
+#### `route`
+
+**Type**: `string`
+
+**Required**: `true`
+
+A route pattern to match against.
+
+#### `rule`
+
+**Type**: `NitroRouteConfig`
+
+**Required**: `true`
+
+A route configuration to apply to the matched route.
+
+#### `options`
+
+**Type**: `ExtendRouteRulesOptions`
+
+**Default**: `{}`
+
+Options to pass to the route configuration. If `override` is set to `true`, it will override the existing route configuration.
+
+### Examples
+
+```ts
+// https://github.com/directus/website/blob/main/modules/redirects.ts
+import { createResolver, defineNuxtModule, extendRouteRules, extendPages } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options) {
+    const resolver = createResolver(import.meta.url)
+
+    extendPages((pages) => {
+      pages.unshift({
+        name: 'preview-new',
+        path: '/preview-new',
+        file: resolver.resolve('runtime/preview.vue')
+       })
+    })
+
+    extendRouteRules('/preview', {
+      redirect: {
+        to: '/preview-new',
+        statusCode: 302
+      }
+    })
+
+    extendRouteRules('/preview-new', {
+      cache: {
+        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
+}
+```
+
+### 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.
+
+- `global` (optional)
+
+  **Type**: `boolean`
+
+  If enabled, registers middleware to be available for all routes.
+
+#### `options`
+
+**Type**: `AddRouteMiddlewareOptions`
+
+**Default**: `{}`
+
+- `override` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  If enabled, overrides the existing middleware with the same name.
+
+- `prepend` (optional)
+
+  **Type**: `boolean`
+
+  **Default**: `false`
+
+  If enabled, prepends the middleware to the list of existing middleware.
+
+### Examples
+
+::code-group
+
+```ts [runtime/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  // isAuthenticated() is an example method verifying if a user is authenticated
+  if (to.path !== '/login' && isAuthenticated() === false) {
+    return navigateTo('/login')
+  }
+})
+```
+
+```ts [module.ts]
+import { createResolver, defineNuxtModule, addRouteMiddleware } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const resolver = createResolver(import.meta.url)
+
+    addRouteMiddleware({
+      name: 'auth',
+      path: resolver.resolve('runtime/auth.ts'),
+      global: true
+    }, { prepend: true })
+  }
+})
+```
+
+::

package/3.api/5.kit/8.layout.md

@@ -0,0 +1,80 @@
+---
+title: "Layout"
+description: "Nuxt Kit provides a set of utilities to help you work with layouts."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/layout.ts
+    size: xs
+---
+
+Layouts is used to be a wrapper around your pages. It can be used to wrap your pages with common components, for example, a header and a footer. Layouts can be registered using `addLayout` utility.
+
+## `addLayout`
+
+Register template as layout and add it to the layouts.
+
+::note
+In Nuxt 2 `error` layout can also be registered using this utility. In Nuxt 3+ `error` layout [replaced](/docs/getting-started/error-handling#rendering-an-error-page) with `error.vue` page in project root.
+::
+
+### Type
+
+```ts
+function addLayout (layout: NuxtTemplate | string, name: string): void
+
+interface NuxtTemplate {
+  src?: string
+  filename?: string
+  dst?: string
+  options?: Record<string, any>
+  getContents?: (data: Record<string, any>) => string | Promise<string>
+  write?: boolean
+}
+```
+
+### Parameters
+
+#### `layout`
+
+**Type**: `NuxtTemplate | string`
+
+**Required**: `true`
+
+A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:
+
+- `src` (optional)
+
+  **Type**: `string`
+
+  Path to the template. If `src` is not provided, `getContents` must be provided instead.
+
+- `filename` (optional)
+
+  **Type**: `string`
+
+  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
+
+- `dst` (optional)
+
+  **Type**: `string`
+
+  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+
+- `options` (optional)
+
+  **Type**: `Options`
+
+  Options to pass to the template.
+
+- `getContents` (optional)
+
+  **Type**: `(data: Options) => string | Promise<string>`
+
+  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` (optional)
+
+    **Type**: `boolean`
+
+    If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.

package/3.api/5.kit/9.plugins.md

@@ -0,0 +1,263 @@
+---
+title: Plugins
+description: Nuxt Kit provides a set of utilities to help you create and use plugins. You can add plugins or plugin templates to your module using these functions.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/plugin.ts
+    size: xs
+---
+
+Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the `plugins` directory. However, if you need to ship a plugin with your module, Nuxt Kit provides the `addPlugin` and `addPluginTemplate` methods. These utils allow you to customize the plugin configuration to better suit your needs.
+
+## `addPlugin`
+
+Registers a Nuxt plugin and to the plugins array.
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugins?friend=nuxt" target="_blank"}
+Watch Vue School video about addPlugin.
+::
+
+### Type
+
+```ts
+function addPlugin (plugin: NuxtPlugin | string, options: AddPluginOptions): NuxtPlugin
+
+interface NuxtPlugin {
+  src: string
+  mode?: 'all' | 'server' | 'client'
+  order?: number
+}
+
+interface AddPluginOptions { append?: boolean }
+```
+
+### Parameters
+
+#### `plugin`
+
+**Type**: `NuxtPlugin | string`
+
+**Required**: `true`
+
+A plugin object or a string with the path to the plugin. If a string is provided, it will be converted to a plugin object with `src` set to the string value. If a plugin object is provided, it must have the following properties:
+
+- `src` (required)
+
+  **Type**: `string`
+
+  Path to the plugin.
+
+- `mode` (optional)
+
+  **Type**: `'all' | 'server' | 'client'`
+
+  **Default**: `'all'`
+
+  If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
+
+- `order` (optional)
+
+  **Type**: `number`
+
+  **Default**: `0`
+
+  Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).
+
+::warning
+Don't use `order` unless you know what you're doing. For most plugins, the default `order` of `0` is sufficient. To append a plugin to the end of the plugins array, use the `append` option instead.
+::
+
+#### `options`
+
+**Type**: `AddPluginOptions`
+
+**Default**: `{}`
+
+Options to pass to the plugin. If `append` is set to `true`, the plugin will be appended to the plugins array instead of prepended.
+
+### Examples
+
+::code-group
+
+```ts [module.ts]
+import { createResolver, defineNuxtModule, addPlugin } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const resolver = createResolver(import.meta.url)
+
+    addPlugin({
+      src: resolver.resolve('runtime/plugin.js'),
+      mode: 'client'
+    })
+  }
+})
+```
+
+```ts [runtime/plugin.js]
+// https://github.com/nuxt/nuxters
+export default defineNuxtPlugin((nuxtApp) => {
+  const colorMode = useColorMode()
+
+  nuxtApp.hook('app:mounted', () => {
+    if (colorMode.preference !== 'dark') {
+      colorMode.preference = 'dark'
+    }
+  })
+})
+```
+
+::
+
+## `addPluginTemplate`
+
+Adds a template and registers as a nuxt plugin. This is useful for plugins that need to generate code at build time.
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/injecting-plugin-templates?friend=nuxt" target="_blank"}
+Watch Vue School video about addPluginTemplate.
+::
+
+### Type
+
+```ts
+function addPluginTemplate (pluginOptions: NuxtPluginTemplate, options: AddPluginOptions): NuxtPlugin
+
+interface NuxtPluginTemplate<Options = Record<string, any>> {
+  src?: string,
+  filename?: string,
+  dst?: string,
+  mode?: 'all' | 'server' | 'client',
+  options?: Options,
+  getContents?: (data: Options) => string | Promise<string>,
+  write?: boolean,
+  order?: number
+}
+
+interface AddPluginOptions { append?: boolean }
+
+interface NuxtPlugin {
+  src: string
+  mode?: 'all' | 'server' | 'client'
+  order?: number
+}
+```
+
+### Parameters
+
+#### `pluginOptions`
+
+**Type**: `NuxtPluginTemplate`
+
+**Required**: `true`
+
+A plugin template object with the following properties:
+
+- `src` (optional)
+
+  **Type**: `string`
+
+  Path to the template. If `src` is not provided, `getContents` must be provided instead.
+
+- `filename` (optional)
+
+  **Type**: `string`
+
+  Filename of the template. If `filename` is not provided, it will be generated from the `src` path. In this case, the `src` option is required.
+
+- `dst` (optional)
+
+  **Type**: `string`
+
+  Path to the destination file. If `dst` is not provided, it will be generated from the `filename` path and nuxt `buildDir` option.
+
+- `mode` (optional)
+
+  **Type**: `'all' | 'server' | 'client'`
+
+  **Default**: `'all'`
+
+  If set to `'all'`, the plugin will be included in both client and server bundles. If set to `'server'`, the plugin will only be included in the server bundle. If set to `'client'`, the plugin will only be included in the client bundle. You can also use `.client` and `.server` modifiers when specifying `src` option to use plugin only in client or server side.
+
+- `options` (optional)
+
+  **Type**: `Options`
+
+  Options to pass to the template.
+
+- `getContents` (optional)
+
+  **Type**: `(data: Options) => string | Promise<string>`
+
+  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` (optional)
+
+    **Type**: `boolean`
+
+    If set to `true`, the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
+
+- `order` (optional)
+
+  **Type**: `number`
+
+  **Default**: `0`
+
+  Order of the plugin. This allows more granular control over plugin order and should only be used by advanced users. Lower numbers run first, and user plugins default to `0`. It's recommended to set `order` to a number between `-20` for `pre`-plugins (plugins that run before Nuxt plugins) and `20` for `post`-plugins (plugins that run after Nuxt plugins).
+
+::warning
+Don't use `order` unless you know what you're doing. For most plugins, the default `order` of `0` is sufficient. To append a plugin to the end of the plugins array, use the `append` option instead.
+::
+
+#### `options`
+
+**Type**: `AddPluginOptions`
+
+**Default**: `{}`
+
+Options to pass to the plugin. If `append` is set to `true`, the plugin will be appended to the plugins array instead of prepended.
+
+### Examples
+
+::code-group
+
+```ts [module.ts]
+// https://github.com/vuejs/vuefire
+import { createResolver, defineNuxtModule, addPluginTemplate } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const resolver = createResolver(import.meta.url)
+
+    addPluginTemplate({
+      src: resolve(templatesDir, 'plugin.ejs'),
+      filename: 'plugin.mjs',
+      options: {
+        ...options,
+        ssr: nuxt.options.ssr,
+      },
+    })
+  }
+})
+```
+
+```ts [runtime/plugin.ejs]
+import { VueFire, useSSRInitialState } from 'vuefire'
+import { defineNuxtPlugin } from '#imports'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const firebaseApp = nuxtApp.$firebaseApp
+
+  nuxtApp.vueApp.use(VueFire, { firebaseApp })
+
+  <% if(options.ssr) { %>
+  if (import.meta.server) {
+    nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
+  } else if (nuxtApp.payload?.vuefire) {
+    useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
+  }
+  <% } %>
+})
+```
+
+::

package/3.api/6.advanced/.navigation.yml

@@ -0,0 +1 @@
+icon: i-lucide-brain