mirror of https://github.com/nuxt/nuxt.git synced 2024-11-30 09:27:13 +00:00

fix(docs): use absolute url for layout description

2023-08-30 00:33:40 +03:00

44 KiB

Raw Blame History

title	description
Kit Utilities	Nuxt Kit provides composable utilities to help interacting with Nuxt Hooks and Nuxt Builder.

Kit Utilities

::ReadMore{link="/docs/guide/going-further/kit"} ::

Modules

source code

Modules are the building blocks of Nuxt. Kit provides a set of utilities to help you create and use modules. You can use these utilities to create your own modules or to reuse existing modules.

`defineNuxtModule`

Define a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.

Type

function defineNuxtModule<OptionsT extends ModuleOptions> (definition: ModuleDefinition<OptionsT> | NuxtModule<OptionsT>): NuxtModule<OptionsT>

type ModuleOptions = Record<string, any>

interface ModuleDefinition<T extends ModuleOptions = ModuleOptions> {
  meta?: ModuleMeta
  defaults?: T | ((nuxt: Nuxt) => T)
  schema?: T
  hooks?: Partial<NuxtHooks>
  setup?: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>
}

interface NuxtModule<T extends ModuleOptions = ModuleOptions> {
  (this: void, inlineOptions: T, nuxt: Nuxt): Awaitable<void | false | ModuleSetupReturn>
  getOptions?: (inlineOptions?: T, nuxt?: Nuxt) => Promise<T>
  getMeta?: () => Promise<ModuleMeta>
}

interface ModuleSetupReturn {
  timings?: {
    setup?: number
    [key: string]: number | undefined
  }
}

interface ModuleMeta {
  name?: string
  version?: string
  configKey?: string
  compatibility?: NuxtCompatibility
  [key: string]: unknown
}

Parameters

`definition`

Type: ModuleDefinition<T> | NuxtModule<T>

Required: true

A module definition object or a module function.

meta (optional)

Type: ModuleMeta

Metadata of the module. It defines the module name, version, config key and compatibility.
defaults (optional)

Type: T | ((nuxt: Nuxt) => T)

Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
schema (optional)

Type: T

Schema for the module options. If provided, options will be applied to the schema.
hooks (optional)

Type: Partial<NuxtHooks>

Hooks to be installed for the module. If provided, the module will install the hooks.
setup (optional)

Type: (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupReturn>

Setup function for the module. If provided, the module will call the setup function.

Examples

// https://github.com/nuxt/starter/tree/module
import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleOptions {}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    test: 123
  },
  setup (options, nuxt) {
    nuxt.hook('modules:done', () => {
      console.log('My module is ready with current test option: ', options.test)
    })    
  }
})

`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.

Type

async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)

Parameters

`moduleToInstall`

Type: string | NuxtModule

Required: true

The module to install. Can be either a string with the module name or a module object itself.

`inlineOptions`

Type: any

Default: {}

An object with the module options to be passed to the module's setup function.

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

Examples

import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule<ModuleOptions>({  
  async setup (options, nuxt) {
    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
    await installModule('@nuxtjs/fontaine', {
      // module configuration
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        }
      ]
    })
  }
})

Programmatic Usage

source code

Programmatic usage can be helpfull when you want to use Nuxt programmatically, for example, when building a CLI tool or test utils.

`loadNuxt`

Load Nuxt programmatically. It will load the Nuxt configuration, instantiate and return the promise with Nuxt instance.

Type

async function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>

interface LoadNuxtOptions extends LoadNuxtConfigOptions {
  dev?: boolean
  ready?: boolean
  rootDir?: string
  config?: LoadNuxtConfigOptions['overrides']
}

Parameters

`loadOptions`

Type: LoadNuxtOptions

Default: {}

Loading conditions for Nuxt. loadNuxt uses c12 under the hood, so it accepts the same options as c12.loadConfig with some additional options:

dev (optional)

Type: boolean

Default: false

If set to true, Nuxt will be loaded in development mode.
ready (optional)

Type: boolean

Default: true

If set to true, Nuxt will be ready to use after the loadNuxt call. If set to false, you will need to call nuxt.ready() to make sure Nuxt is ready to use.
rootDir (optional)

Type: string

Default: null

Deprecated: Use cwd option instead.

The root directory of the Nuxt project.
config (optional)

Type: LoadNuxtConfigOptions['overrides']

Default: {}

Deprecated: Use overrides option instead.

Overrides for the Nuxt configuration.

`buildNuxt`

Build Nuxt programmatically. It will invoke the builder (currently @nuxt/vite-builder or @nuxt/webpack-builder) to bundle the application.

Type

async function buildNuxt (nuxt: Nuxt): Promise<any>

Parameters

`nuxt`

Type: Nuxt

Required: true

Nuxt instance to build. It can be retrieved from the context via useNuxt() call.

`loadNuxtConfig`

Load Nuxt configuration. It will return the promise with the configuration object.

Type

async function loadNuxtConfig (opts: LoadNuxtConfigOptions): Promise<NuxtOptions>

Parameters

`opts`

Type: LoadNuxtConfigOptions

Required: true

Options to pass in c12 loadConfig call.

Compatibility

source code

Kit utilities can be used in Nuxt 3, Nuxt 2 with Bridge and Nuxt 2 without Bridge. To make sure your module is compatible with all versions, you can use the checkNuxtCompatibility, assertNuxtCompatibility and hasNuxtCompatibility functions. They will check if the current Nuxt version meets the constraints you provide. Also you can use isNuxt2, isNuxt3 and getNuxtVersion functions for more granular checks.

`checkNuxtCompatibility`

Checks if constraints are met for the current Nuxt version. If not, returns an array of messages. Nuxt 2 version also checks for bridge support.

Type

async function checkNuxtCompatibility(
  constraints: NuxtCompatibility,
  nuxt?: Nuxt
): Promise<NuxtCompatibilityIssues>;

interface NuxtCompatibility {
  nuxt?: string;
  bridge?: boolean;
}

interface NuxtCompatibilityIssue {
  name: string;
  message: string;
}

interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
  toString(): string;
}

Parameters

`constraints`

Type: NuxtCompatibility

Default: {}

Constraints to check for. It accepts the following properties:

nuxt (optional)

Type: string

Nuxt version in semver format. Versions may be defined in Node.js way, for exmaple: >=2.15.0 <3.0.0.
bridge (optional)

Type: boolean

If set to true, it will check if the current Nuxt version supports bridge.

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

`assertNuxtCompatibility`

Asserts that constraints are met for the current Nuxt version. If not, throws an error with the list of issues as string.

Type

async function assertNuxtCompatibility(
  constraints: NuxtCompatibility,
  nuxt?: Nuxt
): Promise<true>;

interface NuxtCompatibility {
  nuxt?: string;
  bridge?: boolean;
}

Parameters

`constraints`

Type: NuxtCompatibility

Default: {}

Constraints to check for. It accepts the following properties:

nuxt (optional)

Type: string

Nuxt version in semver format. Versions may be defined in Node.js way, for exmaple: >=2.15.0 <3.0.0.
bridge (optional)

Type: boolean

If set to true, it will check if the current Nuxt version supports bridge.

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

`hasNuxtCompatibility`

Checks if constraints are met for the current Nuxt version. Return true if all constraints are met, otherwise returns false. Nuxt 2 version also checks for bridge support.

Type

async function hasNuxtCompatibility(
  constraints: NuxtCompatibility,
  nuxt?: Nuxt
): Promise<boolean>;

interface NuxtCompatibility {
  nuxt?: string;
  bridge?: boolean;
}

Parameters

`constraints`

Type: NuxtCompatibility

Default: {}

Constraints to check for. It accepts the following properties:

nuxt (optional)

Type: string

Nuxt version in semver format. Versions may be defined in Node.js way, for exmaple: >=2.15.0 <3.0.0.
bridge (optional)

Type: boolean

If set to true, it will check if the current Nuxt version supports bridge.

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

`isNuxt2`

Checks if the current Nuxt version is 2.x.

Type

function isNuxt2(nuxt?: Nuxt): boolean;

Parameters

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

`isNuxt3`

Checks if the current Nuxt version is 3.x.

Type

function isNuxt3(nuxt?: Nuxt): boolean;

Parameters

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

`getNuxtVersion`

Returns the current Nuxt version.

Type

function getNuxtVersion(nuxt?: Nuxt): string;

Parameters

`nuxt`

Type: Nuxt

Default: useNuxt()

Nuxt instance. If not provided, it will be retrieved from the context via useNuxt() call.

Auto-imports

source code

::alert{type=info} These functions are designed for registering your own utils, composables and Vue APIs. For pages, components and plugins, please refer to the specific sections: Pages, Components, Plugins. ::

Nuxt auto-imports helper functions, composables and Vue APIs to use across your application without explicitly importing them. Based on the directory structure, every Nuxt application can also use auto-imports for its own composables and plugins. Composables or plugins can use these functions.

`addImports`

Add imports to the Nuxt application. It makes your imports available in the Nuxt application without the need to import them manually.

Type

function addImports (imports: Import | Import[]): void

interface Import {
  from: string
  priority?: number
  disabled?: boolean
  meta?: {
    description?: string
    docsUrl?: string
    [key: string]: any
  }
  type?: boolean
  typeFrom?: string
  name: string
  as?: string
}

Parameters

`imports`

Type: Import | Import[]

Required: true

An object or an array of objects with the following properties:

from (required)

Type: string

Module specifier to import from.
priority (optional)

Type: number

Default: 1

Priority of the import, if multiple imports have the same name, the one with the highest priority will be used.
disabled (optional)

Type: boolean

If this import is disabled.
meta (optional)

Type: object

Metadata of the import.
meta.description (optional)

Type: string

Short description of the import.
meta.docsUrl (optional)

Type: string

URL to the documentation.
meta[key] (optional)

Type: any

Additional metadata.
type (optional)

Type: boolean

If this import is a pure type import.
typeFrom (optional)

Type: string

Using this as the from when generating type declarations.
name (required)

Type: string

Import name to be detected.
as (optional)

Type: string

Import as this name.

Examples

// https://github.com/pi0/storyblok-nuxt
import { defineNuxtModule, addImports, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    const names = [
      "useStoryblok",
      "useStoryblokApi",
      "useStoryblokBridge",
      "renderRichText",
      "RichTextSchema"
    ];

    names.forEach((name) =>
      addImports({ name, as: name, from: "@storyblok/vue" })
    );
  }
})

`addImportsDir`

Add imports from a directory to the Nuxt application. It will automatically import all files from the directory and make them available in the Nuxt application without the need to import them manually.

Type

function addImportsDir (dirs: string | string[], opts?: { prepend?: boolean })

Parameters

`dirs`

Type: string | string[]

Required: true

A string or an array of strings with the path to the directory to import from.

`opts`

Type: { prepend?: boolean }

Default: {}

Options to pass to the import. If prepend is set to true, the imports will be prepended to the list of imports.

Examples

// https://github.com/vueuse/motion/tree/main/src/nuxt
import { defineNuxtModule, addImportsDir, createResolver } from '@nuxt/kit'

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: '@vueuse/motion',
    configKey: 'motion',
  },
  defaults: {},
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    addImportsDir(resolve('./runtime/composables'))
  },
})

`addImportsSources`

Add listed imports to the Nuxt application.

Type

function addImportsSources (importSources: ImportSource | ImportSource[])

interface Import {
  from: string
  priority?: number
  disabled?: boolean
  meta?: {
    description?: string
    docsUrl?: string
    [key: string]: any
  }
  type?: boolean
  typeFrom?: string
  name: string
  as?: string
}

interface ImportSource extends Import {
  imports: (PresetImport | ImportSource)[]
}

type PresetImport = Omit<Import, 'from'> | string | [name: string, as?: string, from?: string]

Parameters

`importSources`

Type: ImportSource | ImportSource[]

Required: true

An object or an array of objects with the following properties:

imports (required)

Type: PresetImport | ImportSource[]

Required: true

An object or an array of objects, which can be import names, import objects or import sources.
from (required)

Type: string

Module specifier to import from.
priority (optional)

Type: number

Default: 1

Priority of the import, if multiple imports have the same name, the one with the highest priority will be used.
disabled (optional)

Type: boolean

If this import is disabled.
meta (optional)

Type: object

Metadata of the import.
meta.description (optional)

Type: string

Short description of the import.
meta.docsUrl (optional)

Type: string

URL to the documentation.
meta[key] (optional)

Type: any

Additional metadata.
type (optional)

Type: boolean

If this import is a pure type import.
typeFrom (optional)

Type: string

Using this as the from when generating type declarations.
name (required)

Type: string

Import name to be detected.
as (optional)

Type: string

Import as this name.

Examples

// https://github.com/elk-zone/elk
import { defineNuxtModule, addImportsSources } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    // add imports from h3 to make them autoimported
    addImportsSources({
      from: 'h3',
      imports: ['defineEventHandler', 'getQuery', 'getRouterParams', 'readBody', 'sendRedirect'] as Array<keyotypeof import('h3')>,
    })
  }
})

Components

source code

In Nuxt, components from the components directory are automatically imported by default. However, if you need to import components from an alternative directory or wish to selectively import them as needed, @nuxt/kit provides the addComponentsDir and addComponent methods. These utils allow you to customize the component configuration to better suit your needs.

`addComponentsDir`

Register a directory to be scanned for components and imported only when used. Keep in mind, that this does not register components globally, until you specify global: true option.

Type

async function addComponentsDir (dir: ComponentsDir): void

interface ComponentsDir {
  path: string
  pattern?: string | string[]
  ignore?: string[]
  prefix?: string
  pathPrefix?: boolean
  enabled?: boolean
  prefetch?: boolean
  preload?: boolean
  isAsync?: boolean
  extendComponent?: (component: Component) => Promise<Component | void> | (Component | void)
  global?: boolean
  island?: boolean
  watch?: boolean
  extensions?: string[]
  transpile?: 'auto' | boolean
}

interface Component {
  pascalName: string
  kebabName: string
  export: string
  filePath: string
  shortPath: string
  chunkName: string
  prefetch: boolean
  preload: boolean
  global?: boolean
  island?: boolean
  mode?: 'client' | 'server' | 'all'
  priority?: number
}

Parameters

`dir`

Type: ComponentsDir

Required: true

An object with the following properties:

path (required)

Type: string

Path (absolute or relative) to the directory containing your components. You can use Nuxt aliases (~ or @) to refer to directories inside project or directly use an npm package path similar to require.
pattern (optional)

Type: string | string[]

Accept Pattern that will be run against specified path.
ignore (optional)

Type: string[]

Ignore patterns that will be run against specified path.
prefix (optional)

Type: string

Prefix all matched components with this string.
pathPrefix (optional)

Type: boolean

Prefix component name by its path.
enabled (optional)

Type: boolean

Ignore scanning this directory if set to true.
prefetch (optional)

Type: boolean

These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. Learn more on webpack documentation
preload (optional)

Type: boolean

These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. Learn more on webpack documentation
isAsync (optional)

Type: boolean

This flag indicates, component should be loaded async (with a separate chunk) regardless of using Lazy prefix or not.
extendComponent (optional)

Type: (component: Component) => Promise<Component | void> | (Component | void)

A function that will be called for each component found in the directory. It accepts a component object and should return a component object or a promise that resolves to a component object.
global (optional)

Type: boolean

Default: false

If enabled, registers components to be globally available.
island (optional)

Type: boolean

If enabled, registers components as islands.
watch (optional)

Type: boolean

Watch specified path for changes, including file additions and file deletions.
extensions (optional)

Type: string[]

Extensions supported by Nuxt builder.
transpile (optional)

Type: 'auto' | boolean

Transpile specified path using build.transpile. If set to 'auto', it will set transpile: true if node_modules/ is in path.

`addComponent`

Type

async function addComponent (opts: AddComponentOptions): void

interface AddComponentOptions {
  name: string,
  filePath: string,
  pascalName?: string,
  kebabName?: string,
  export?: string,
  shortPath?: string,
  chunkName?: string,
  prefetch?: boolean,
  preload?: boolean,
  global?: boolean,
  island?: boolean,
  mode?: 'client' | 'server' | 'all',
  priority?: number,
}

Parameters

`opts`

Type: AddComponentOptions

Required: true

An object with the following properties:

name (required)

Type: string

Component name.
filePath (required)

Type: string

Path to the component.
pascalName (optional)

Type: pascalCase(opts.name)

Pascal case component name. If not provided, it will be generated from the component name.
kebabName (optional)

Type: kebabCase(opts.name)

Kebab case component name. If not provided, it will be generated from the component name.
export (optional)

Type: string

Default: 'default'

Specify named or default export. If not provided, it will be set to 'default'.
shortPath (optional)

Type: string

Short path to the component. If not provided, it will be generated from the component path.
chunkName (optional)

Type: string

Default: 'components/' + kebabCase(opts.name)

Chunk name for the component. If not provided, it will be generated from the component name.
prefetch (optional)

Type: boolean

These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. Learn more on webpack documentation
preload (optional)

Type: boolean

These properties (prefetch/preload) are used in production to configure how components with Lazy prefix are handled by webpack via its magic comments. Learn more on webpack documentation
global (optional)

Type: boolean

Default: false

If enabled, registers component to be globally available.
island (optional)

Type: boolean

If enabled, registers component as island. You can read more about islands in component description.
mode (optional)

Type: 'client' | 'server' | 'all'

Default: 'all'

This options indicates if component should render on client, server or both. By default, it will render on both client and server.
priority (optional)

Type: number

Default: 1

Priority of the component, if multiple components have the same name, the one with the highest priority will be used.

Context

source code

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.

::alert{type=info} 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 as an example of usage. ::

`useNuxt`

Get the Nuxt instance from the context. It will throw an error if Nuxt is not available.

Type

function useNuxt(): Nuxt

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>
}

Examples

::code-group

// https://github.com/Lexpeartha/nuxt-xstate/blob/main/src/parts/transpile.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',
    )
  }
}

import { useNuxt } from '@nuxt/kit'
import { setupTranspilation } from './setupTranspilation'

export default defineNuxtModule({
  setup() {
    setupTranspilation()
  }
})

`tryUseNuxt`

Get the Nuxt instance from the context. It will return null if Nuxt is not available.

Type

function tryUseNuxt(): Nuxt | null

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>
}

Examples

::code-group

// https://github.com/harlan-zw/nuxt-site-config/blob/main/test/assertions.test.ts
import { tryUseNuxt } from '@nuxt/kit'

interface SiteConfig {
  title: string
}

export const requireSiteConfig = (): SiteConfig => {
  const nuxt = tryUseNuxt()
  if (!nuxt) {
    return { title: null }
  }
  return nuxt.options.siteConfig
}

import { useNuxt } from '@nuxt/kit'
import { requireSiteConfig } from './requireSiteConfig'

export default defineNuxtModule({
  setup(_, nuxt) {
    const config = requireSiteConfig()
    nuxt.options.app.head.title = config.title
  }
})

Pages

source code

`extendPages`

In Nuxt 3, 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 3 offers the extendPages feature, which allows you to extend and alter the pages configuration.

Type

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

// 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 server engine. With Nitro, you can incorporate high-level logic directly into your configuration, which is usefull for actions like redirects, proxying, caching, and appending headers to routes. This configuration works by associating route patterns with specific route settings.

::alert{type=info icon=👉} You can read more about Nitro route rules in the Nitro documentation. ::

Type

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

// 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 composable.

::alert{type=info icon=👉} Read more about route middlewares in the Route middleware documentation. ::

Type

function addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options: AddRouteMiddlewareOptions)

type NuxtMiddleware = {
  name: string
  path: string
  global?: boolean
}

interface AddRouteMiddlewareOptions {
  override?: 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: {}

Options to pass to the middleware. If override is set to true, it will override the existing middleware with the same name.

Examples

::code-group

export default defineNuxtRouteMiddleware((to, from) => {
  // isAuthenticated() is an example method verifying if a user is authenticated
  if (isAuthenticated() === false) {
    return navigateTo('/login')
  }
})

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
    })
  }
})

Layout

source code

`addLayout`

::alert{type=info icon=👉} In Nuxt 2 error layout can also be registered using this utility. In Nuxt 3 error layout replaced with error.vue page in project root. ::

Type

function addLayout (layout: NuxtTemplate, 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

Required: true

A 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.
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.

Plugins

source code

`addPlugin`

Registers a Nuxt plugin and to the plugins array.

Type

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).

::alert{type=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

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'
    })
  }
})

// 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.

Type

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).

`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

// 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'),
      options: {
        ...options,
        ssr: nuxt.options.ssr,
      },
    })
  }
})

import { VueFire, useSSRInitialState } from 'vuefire'
import { defineNuxtPlugin } from '#app'

export default defineNuxtPlugin((nuxtApp) => {
  const firebaseApp = nuxtApp.$firebaseApp

  nuxtApp.vueApp.use(VueFire, { firebaseApp })

  <% if(options.ssr) { %>
  if (process.server) {
    nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
  } else if (nuxtApp.payload?.vuefire) {
    useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
  }
  <% } %>
})

Templates

source code

addTemplate(templateOptions)
addTypeTemplate(templateOptions)
updateTemplates({ filter?: ResolvedNuxtTemplate => boolean })

Nitro

source code

addServerHandler (handler)
addDevServerHandler (handler)
useNitro() (only usable after ready hook)
addServerPlugin
addPrerenderRoutes

Resolving

source code

resolvePath (path, resolveOptions?)
resolveAlias (path, aliases?)
findPath (paths, resolveOptions?)
createResolver (base)

Logging

source code

useLogger(scope?)

Builder

source code

extendWebpackConfig(callback, options?)
extendViteConfig(callback, options?)
addWebpackPlugin(webpackPlugin, options?)
addVitePlugin(vitePlugin, options?)

Examples

Accessing Nuxt Vite Config

If you are building an integration that needs access to the runtime Vite or webpack config that Nuxt uses, it is possible to extract this using Kit utilities.

Some examples of projects doing this already:

Here is a brief example of how you might access the Vite config from a project; you could implement a similar approach to get the webpack configuration.

import { loadNuxt, buildNuxt } from '@nuxt/kit'

// https://github.com/nuxt/nuxt/issues/14534
async function getViteConfig() {
  const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
  return new Promise((resolve, reject) => {
    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
      if (isClient) {
        resolve(config)
        throw new Error('_stop_')
      }
    })
    buildNuxt(nuxt).catch((err) => {
      if (!err.toString().includes('_stop_')) {
        reject(err)
      }
    })
  }).finally(() => nuxt.close())
}

const viteConfig = await getViteConfig()
console.log(viteConfig)

44 KiB Raw Blame History

Kit Utilities

Modules

defineNuxtModule

Type

Parameters

definition

Examples

installModule

Type

Parameters

moduleToInstall

inlineOptions

nuxt

Examples

Programmatic Usage

loadNuxt

Type

Parameters

loadOptions

buildNuxt

Type

Parameters

nuxt

loadNuxtConfig

Type

Parameters

opts

Compatibility

checkNuxtCompatibility

Type

Parameters

constraints

nuxt

assertNuxtCompatibility

Type

Parameters

constraints

nuxt

hasNuxtCompatibility

Type

Parameters

constraints

nuxt

isNuxt2

Type

Parameters

nuxt

isNuxt3

Type

Parameters

nuxt

getNuxtVersion

Type

Parameters

nuxt

Auto-imports

addImports

Type

Parameters

imports

Examples

addImportsDir

Type

Parameters

dirs

opts

Examples

addImportsSources

Type

Parameters

importSources

Examples

Components

addComponentsDir

Type

Parameters

dir

addComponent

Type

44 KiB

Raw Blame History

`defineNuxtModule`

`definition`

`installModule`

`moduleToInstall`

`inlineOptions`

`nuxt`

`loadNuxt`

`loadOptions`

`buildNuxt`

`nuxt`

`loadNuxtConfig`

`opts`

`checkNuxtCompatibility`

`constraints`

`nuxt`

`assertNuxtCompatibility`

`constraints`

`nuxt`

`hasNuxtCompatibility`

`constraints`

`nuxt`

`isNuxt2`

`nuxt`

`isNuxt3`

`nuxt`

`getNuxtVersion`

`nuxt`

`addImports`

`imports`

`addImportsDir`

`dirs`

`opts`

`addImportsSources`

`importSources`

`addComponentsDir`

`dir`

`addComponent`

`opts`

`useNuxt`

`tryUseNuxt`

`extendPages`

`callback`

`extendRouteRules`

`route`

`rule`

`options`

`addRouteMiddleware`

`input`

`options`

`addLayout`

`layout`

`addPlugin`

`plugin`

`options`

`addPluginTemplate`

`pluginOptions`

`options`