Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
097d040
docs: add module-builder docs for nuxt.com
danielroe Nov 12, 2026
05a4701
docs: set the root `types` field for node10 consumers
danielroe Nov 13, 2026
1b95309
docs: address comments 🐰
danielroe Nov 13, 2026
f14aa31
docs: add the `nuxt build-module` command page
danielroe Nov 13, 2026
015b329
docs: stop recommending node10 `types` and `typesVersions`
danielroe Nov 13, 2026
867ff88
test: normalise line endings when reading command docs
danielroe Nov 13, 2026
d74942a
docs: use `src/runtime/app` and `src/runtime/server` in examples
danielroe Nov 13, 2026
784d970
docs: add a page on developing and publishing a module
danielroe Nov 13, 2026
2493e8d
docs: separate the app's type contexts from the module's own type check
danielroe Nov 13, 2026
83cd754
docs: start the playground without `dev:prepare` to try the build
danielroe Nov 13, 2026
1d07727
docs: note that the docs describe Nuxt 4 and later
danielroe Nov 13, 2026
a123f3a
docs: use a non-secret option in the public runtime config example
danielroe Nov 13, 2026
03fe05d
docs: run publint on the packed tarball
danielroe Nov 13, 2026
6920021
docs: set runtime config with `updateRuntimeConfig` in the module exa…
danielroe Nov 13, 2026
e9e1a6a
docs: describe the root export's value and type exports
danielroe Nov 13, 2026
a532eea
docs: describe building with `tsdown` and remove `--stub` from the co…
danielroe Nov 15, 2026
2f0708c
docs: describe source exports, developing against `dist` and the publ…
danielroe Nov 15, 2026
74c1e7b
docs: configure the build with `builder()` in `tsdown.config.ts`
danielroe Nov 15, 2026
6feeb52
docs: describe module code that loads with Node and the playground's …
danielroe Nov 15, 2026
5d668f1
docs: describe the size report and the source types that `prepare` wr…
danielroe Nov 15, 2026
cf862f9
docs: describe subpath exports with source exports
danielroe Nov 15, 2026
c00efbe
docs: show source exports and `tsdown.config.ts` in the project struc…
danielroe Nov 15, 2026
6c25ec5
docs: set up a module with `tsdown.config.ts` in getting started
danielroe Nov 15, 2026
25a1ab5
docs: describe tsdown builds and source exports in the README
danielroe Nov 15, 2026
121f41e
docs: attribute the default `transform` to `builder()`
danielroe Nov 15, 2026
79765e4
docs: cover reading runtime file contents and root `nuxt prepare` wit…
danielroe Nov 15, 2026
20e8bd0
docs: fix the size check, type-only import extensions and the `types`…
danielroe Nov 15, 2026
b2c4f41
docs: rewrite
danielroe Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 21 additions & 187 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,204 +9,36 @@

## Features

- Compatible with Nuxt 3 and Nuxt Kit
- Unified build with [tsdown](https://tsdown.dev)
- 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.

If you're upgrading a module from v1, follow the [upgrade guide](./docs/upgrade-v2.md).

## 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+.
- Builds modules for Nuxt 3 and later, with no configuration for the [module starter](https://github.com/nuxt/starter/tree/module) layout
- Builds with [tsdown](https://tsdown.dev) through the `builder()` plugin: bundles the module entry, and transpiles the runtime directory file by file
- Generates declarations against the module's own `.nuxt`, for `.ts` and `.vue` files alike
- Writes the type shims that give `nuxt.config` autocompletion for the module's options and hooks
- Lets a playground run the module's sources while `package.json` publishes `dist`, and checks the published paths before every build

## Quick start

Get started with our [module starter](https://github.com/nuxt/starter/tree/module):
Create a module from the [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 is transpiled individually to `dist/runtime/`.

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

### `package.json`:

A minimum `package.json` should look like this. It points at the module's sources while you develop, and pnpm publishes the `dist` paths in `publishConfig` in their place:

```json [package.json]
{
"name": "my-module",
"license": "MIT",
"version": "1.0.0",
"exports": {
".": {
"types": "./.nuxt/module-builder/types.d.mts",
"import": "./src/module.ts"
}
},
"main": "./src/module.ts",
"types": "./.nuxt/module-builder/types.d.mts",
"files": [
"dist"
],
"publishConfig": {
"exports": {
".": {
"types": "./dist/types.d.mts",
"import": "./dist/module.mjs"
}
},
"main": "./dist/module.mjs",
"types": "./dist/types.d.mts"
},
"scripts": {
"dev": "nuxt dev playground",
"dev:prepare": "nuxt-module-build prepare && nuxt prepare playground",
"prepack": "tsdown"
},
"dependencies": {
"@nuxt/kit": "latest"
},
"devDependencies": {
"@nuxt/module-builder": "latest",
"tsdown": "^0.23.7"
}
}
```

`tsdown` is a peer dependency, so install it alongside `@nuxt/module-builder`. `tsdown` builds the module with the `tsdown.config.ts` shown in [Build configuration](#build-configuration); without one, use `"prepack": "nuxt-module-build build"` instead. `nuxt-module-build prepare` writes `.nuxt/module-builder/types.d.mts`, the declarations of `src/module.ts` with the module's type augmentations. pnpm and Yarn 4 publish `publishConfig` in place of these fields; npm, Yarn 3 and earlier, and bun don't, and packing with them fails. With those, point `package.json` at `dist` and run `tsdown --watch` while you develop. See [Developing a module](./docs/upgrade-v2.md#developing-a-module).

Module code (`src/module.ts`, the files it imports by value, and the build config) has to load with Node as it is: relative imports carry their `.ts` extension, and TypeScript syntax that stripping types doesn't remove, tsconfig `paths` aliases, value imports of `.vue` and `.tsx` files, JSON without `with { type: 'json' }`, and value imports of `#app`, `#imports`, and `#build/*` aren't allowed. See [Module code loads with Node](./docs/upgrade-v2.md#module-code-loads-with-node).
Building a module requires Node `^22.18.0 || >=24.0.0`, with `tsdown` and `typescript` installed alongside `@nuxt/module-builder`. Apps that install a built module need Nuxt 3 or later.

### Build configuration
## Documentation

Module builder builds with [tsdown](https://tsdown.dev), through the `builder()` plugin. Add it to a `tsdown.config.ts`, and build with `tsdown`:
- [Getting started](./docs/index.md)
- [Project structure](./docs/1.project-structure.md)
- [Commands](./docs/2.commands.md): `tsdown`, `build`, and `prepare`
- [Develop and publish](./docs/3.develop-and-publish.md): source exports, the playground, and releasing to npm
- [Configuration](./docs/4.configuration.md): `builder()` in `tsdown.config.ts`, extra entries, and the deprecated `build.config.ts`
- [TypeScript](./docs/5.typescript.md): the module's `tsconfig.json`, and its declarations
- [Build output](./docs/6.output.md)
- [Exports](./docs/7.exports.md): subpath exports, including runtime components
- [Transpiling a directory](./docs/8.transpile-dir.md): the `transpileDir` rolldown plugin
- [Upgrading to v2](./docs/upgrade-v2.md)

```ts [tsdown.config.ts]
import { builder } from '@nuxt/module-builder/tsdown'
import { defineConfig } from 'tsdown'

export default defineConfig({
plugins: [
builder({
// entrypoints other than `src/module`
entries: ['./src/utils'],
}),
],
})
```

`nuxt-module-build build` builds the same `dist`, with this config or, without one, with no options. `builder()` also takes `externals` and `replace`, and other tsdown options apply as usual apart from the ones the plugin sets. See [tsdown config](./docs/upgrade-v2.md#tsdown-config) in the upgrade guide.

> [!WARNING]
> `build.config.ts` and the `unbuild` field of `package.json` are deprecated. Without a `tsdown.config.ts`,
> the build still applies their `entries`, `externals`, `replace`, `rollup.replace`, and `sourcemap` options,
> and the `build:before`, `rollup:done`, and `build:done` hooks, and reads `build.entries` from `package.json`.
> See [Moving from build.config.ts](./docs/upgrade-v2.md#moving-from-buildconfigts) in the upgrade guide.

## 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 transpiled files
- JavaScript and `.ts` files are transpiled to `.js`, with their types extracted to a `.d.ts` file of the same name
- `.vue` files are transpiled to `.vue`, with their types extracted to `.vue.d.ts` and `.d.vue.ts` files
- `.css` files have their nesting flattened, and are vendor-prefixed and minified
- `.scss` and `.sass` files are compiled to `.css` with the module's `sass` or `sass-embedded`; `_` partials aren't emitted
- Other files are copied as they are

## Output size

Each build reports its output size: a summary plus one line per bundled entry and runtime directory for a module with runtime directories, or one line per file otherwise. Set `report` in `tsdown.config.ts` to change it (`{ summary: true }`, `{ gzip: false }`, `{ brotli: true }`, or `false`). For size checks in CI, `npm pack --dry-run --json` lists exactly what gets published: each file's `size`, plus the gzipped tarball's `size` and the `unpackedSize`:

```bash
npm pack --dry-run --json | jq '.[0] | { size, unpackedSize }'
```

## Transpiling a directory with tsdown

The runtime build is a rolldown plugin, `transpileDir`, exported from `@nuxt/module-builder/rolldown`. Use it in any tsdown or rolldown build that transpiles a directory file by file instead of bundling it:

```ts
// tsdown.config.ts
import { defineConfig } from 'tsdown'
import { transpileDir } from '@nuxt/module-builder/rolldown'

export default defineConfig({
entry: ['src/index.ts'],
plugins: [
transpileDir({ srcDir: 'src/runtime', outBase: 'runtime' }),
],
})
```

Every file under `srcDir` is emitted under `outBase` in the build's output directory, with its name intact apart from the extension. Scripts become `.js` (or `.mjs`), and compiled Sass becomes `.css`. Test and story files are excluded by default. Scripts are transpiled with oxc and keep their imports as written, apart from relative imports, which get the emitted extension. `.vue` files are transpiled with `vue-sfc-transformer`, stylesheets are processed as described in [Dist files](#dist-files), and other files are copied. Declarations come from one TypeScript program that uses the nearest `tsconfig.json`.

The options are documented on the `TranspileDirOptions` type. The `resolveExternal` option controls what happens to relative imports that resolve outside `srcDir`. A build with nothing to bundle can pass `emptyEntry`, from the same export, as its `entry`.
For writing the module itself, read the [Nuxt Module Author Guide](https://nuxt.com/docs/guide/modules).

## 💻 Development

Expand All @@ -215,6 +47,8 @@ The options are documented on the `TranspileDirOptions` type. The `resolveExtern
- Install dependencies using `pnpm install`
- Try building [example module](./example) using `pnpm example:build`

Pages in [`docs/`](./docs) are written for [nuxt.com](https://nuxt.com), so links between them use nuxt.com paths.

## License

[MIT](./LICENSE) - Made with 💚
Expand Down
3 changes: 3 additions & 0 deletions docs/.navigation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
title: Module Builder
titleTemplate: '%s · Nuxt Module Builder'
icon: i-lucide-package
Loading
Loading