---
title: "Kit Utilities"
description: 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](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/module)

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

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

```ts
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](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/loader)

Programmatic usage can be helpfull when you want to use Nuxt programmatically, for example, when building a [CLI tool](https://github.com/nuxt/cli) or [test utils](https://github.com/nuxt/nuxt/tree/main/packages/test-utils).

### `loadNuxt`

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

#### Type

```ts
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`](https://github.com/unjs/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](https://github.com/nuxt/nuxt/tree/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)) to bundle the application.

#### Type

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

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

#### Parameters

##### `opts`

**Type**: `LoadNuxtConfigOptions`

**Required**: `true`

Options to pass in [`c12`](https://github.com/unjs/c12#options) `loadConfig` call.

## Compatibility

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/compatibility.ts)

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

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

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

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

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

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

```ts
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](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/imports.ts)

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

## Components

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/components.ts)

- `addComponentsDir(dir)`
- `addComponent(componentObject)`

## Context

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/context.ts)

- `useNuxt()`

## Pages

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/pages.ts)

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

## Plugins

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/plugin.ts)

- `addPlugin(pluginOptions, { append? })`
- `addPluginTemplate(pluginOptions, { append? })`

## Templates

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/template.ts)

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

## Nitro

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts)

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

## Resolving

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/resolve.ts)

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

## Logging

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/logger.ts)

- `useLogger(scope?)`

## Builder

[source code](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/build.ts)

- `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](https://github.com/histoire-dev/histoire/blob/main/packages/histoire-plugin-nuxt/src/index.ts)
- [nuxt-vitest](https://github.com/danielroe/nuxt-vitest/blob/main/packages/nuxt-vitest/src/config.ts)
- [@storybook-vue/nuxt](https://github.com/storybook-vue/nuxt/blob/main/src/preset.ts)

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.

```js
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)
```