Nuxt/docs/3.api/4.advanced/2.kit.md

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

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

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

• addImports(imports)
• addImportsDir(importDirs, { prepend? })
• addImportsSources(importSources)

Components

source code

• addComponentsDir(dir)
• addComponent(componentObject)

Context

source code

• useNuxt()

Pages

source code

• extendPages (callback: pages => void)
• extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)
• addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], options: AddRouteMiddlewareOptions)

Plugins

source code

• addPlugin(pluginOptions, { append? })
• addPluginTemplate(pluginOptions, { append? })

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:

• histoire
• nuxt-vitest
• @storybook-vue/nuxt

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)