# @nuxt/module-builder

> Complete solution for building Nuxt modules

Latest version **1.0.3** (published 2026-07-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nuxt/module-builder
pnpm add @nuxt/module-builder
yarn add @nuxt/module-builder
bun add @nuxt/module-builder
```

Provides the commands `nuxt-build-module`, `nuxt-module-build`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2026-07-23 |
| First published | 2021-12-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | ^18.0.0 \|\| >=20.0.0 |
| Dependencies | 12 |
| Unpacked size | 22.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | danielroe |

## Links

- npm: https://www.npmjs.com/package/@nuxt/module-builder
- Repository: https://github.com/nuxt/module-builder
- Homepage: https://github.com/nuxt/module-builder#readme
- Issues: https://github.com/nuxt/module-builder/issues
- npm.io page: https://npm.io/package/@nuxt/module-builder

## Dependencies (12)

- [defu](https://npm.io/package/defu.md) ^6.1.7
- [jiti](https://npm.io/package/jiti.md) ^2.7.0
- [mlly](https://npm.io/package/mlly.md) ^1.8.2
- [citty](https://npm.io/package/citty.md) ^0.2.2
- [pathe](https://npm.io/package/pathe.md) ^2.0.3
- [mkdist](https://npm.io/package/mkdist.md) ^2.4.1
- [consola](https://npm.io/package/consola.md) ^3.4.2
- [unbuild](https://npm.io/package/unbuild.md) ^3.6.1
- [tsconfck](https://npm.io/package/tsconfck.md) ^3.1.6
- [pkg-types](https://npm.io/package/pkg-types.md) ^2.3.1
- [magic-regexp](https://npm.io/package/magic-regexp.md) ^0.11.0
- [vue-sfc-transformer](https://npm.io/package/vue-sfc-transformer.md) ^0.2.3

## Recent versions

- 1.0.3 (latest) — 2026-07-23
- 1.0.0-alpha.3 (alpha) — 2025-04-04
- 1.0.2 — 2025-07-25
- 1.0.1 — 2025-04-08
- 1.0.0 — 2025-04-04
- 1.0.0-alpha.2 — 2025-04-04
- 1.0.0-alpha.1 — 2025-01-06
- 1.0.0-alpha.0 — 2024-12-13
- 0.8.4 — 2024-09-10
- 0.8.3 — 2024-08-13
- 0.8.2 — 2024-08-13
- 0.8.1 — 2024-06-28
- 0.8.0 — 2024-06-19
- 0.7.1 — 2024-06-11
- 0.7.0 — 2024-05-22
- … 20 more at https://npm.io/package/@nuxt/module-builder/versions

## README

# 📦 Nuxt Module Builder

[![npm version][npm-version-src]][npm-version-href]
[![License][license-src]][license-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
<a href="https://volta.net/nuxt/module-builder?utm_source=nuxt_module_builder_readme"><img src="https://user-images.githubusercontent.com/904724/209143798-32345f6c-3cf8-4e06-9659-f4ace4a6acde.svg" alt="Volta board"></a>

> The complete solution to build and ship [Nuxt modules](https://nuxt.com/modules).

## Features

- Compatible with Nuxt 3 and Nuxt Kit
- Unified build with [unjs/unbuild](https://github.com/unjs/unbuild)
- Automated build config using last module spec
- Typescript and ESM support
- Auto generated types and shims for `@nuxt/schema`

We recommend to checkout the [Nuxt modules author guide](https://nuxt.com/docs/guide/going-further/modules) before starting with the module-builder.

## Requirements

For a user to use a module generated from module-builder, it's recommended they have:
- Node.js >= 18.x. _Latest Node LTS preferred_
- Nuxt 3+.

## Quick start

Get started with our [module starter](https://github.com/nuxt/starter/tree/module):

```bash
npm create nuxt -- -t module my-module
```

## Project structure

The module builder requires a special project structure. You can check out the [module template](https://github.com/nuxt/starter/tree/module).

### `src/module.ts`

The entrypoint for module definition.

A default export using `defineNuxtModule` and `ModuleOptions` type export is expected.

You could also optionally export `ModuleHooks` or `ModuleRuntimeHooks` to annotate any custom hooks the module uses.

```ts [src/module.ts]
import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleOptions {
  apiKey: string
}

export interface ModuleHooks {
  'my-module:init': any
}

export interface ModuleRuntimeHooks {
  'my-module:runtime-hook': any
}

export interface ModuleRuntimeConfig {
  PRIVATE_NAME: string
}

export interface ModulePublicRuntimeConfig {
  NAME: string
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    apiKey: 'test'
  },
  async setup (moduleOptions, nuxt) {
    // Write module logic in setup function
  }
})
```

### `src/runtime/`

Any runtime file and code that we need to provide by module including plugins, composables and server api, should be in this directory.

Each file will be transformed individually using [unjs/mkdist](https://github.com/unjs/mkdist) to `dist/runtime/`.

<!-- TODO: Docs about how to address runtime from within setup -->

### `package.json`:

A minimum `package.json` should look like this:

```json [package.json]
{
  "name": "my-module",
  "license": "MIT",
  "version": "1.0.0",
  "exports": {
    ".": {
      "types": "./dist/types.d.mts",
      "import": "./dist/module.mjs"
    }
  },
  "main": "./dist/module.mjs",
  "typesVersions": {
    "*": {
      ".": [
        "./dist/types.d.mts"
      ]
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "prepack": "nuxt-module-build build"
  },
  "dependencies": {
    "@nuxt/kit": "latest"
  },
  "devDependencies": {
    "@nuxt/module-builder": "latest"
  }
}
```

### `build.config.ts` (optional)

Module builder is essentially a preset for [unjs/unbuild](https://github.com/unjs/unbuild), check out the [build command](./src/commands/build.ts#L51) for reference.

To customize/extend the unbuild configuration you can add a `build.config.ts` in the root of your project:

```ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  // set additional configuration or customize using hooks
})
```

## Dist files

Module builder generates dist files in `dist/` directory:

- `module.mjs`: Module entrypoint build from `src/module`
- `module.json`: Module meta extracted from `module.mjs` + `package.json`
- `types.d.mts`: Exported types in addition to shims for `nuxt.config` auto completion.
- `runtime/*`: Individually transformed files using [unjs/mkdist](https://github.com/unjs/mkdist)
  - Javascript and `.ts` files will be transformed to `.js` with extracted types on `.d.ts` file with same name
  - `.vue` files will be transformed with extracted `.d.ts` file
  - Other files will be copied as is

## 💻 Development

- Clone repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Try building [example module](./example) using `pnpm example:build`

## License

[MIT](./LICENSE) - Made with 💚

<!-- Badges -->
[npm-version-src]: https://npmx.dev/api/registry/badge/version/@nuxt/module-builder
[npm-version-href]: https://npmx.dev/package/@nuxt/module-builder

[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads/@nuxt/module-builder
[npm-downloads-href]: https://npm.chart.dev/@nuxt/module-builder

[license-src]: https://img.shields.io/github/license/nuxt/module-builder.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://github.com/nuxt/module-builder/blob/main/LICENSE

---
_Source: https://npm.io/package/@nuxt/module-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._