Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
1fb9b5e
test: consolidate fixtures into one spec per surface
danielroe Nov 17, 2026
06e99d7
fix: address audit findings in the build, loader and docs
danielroe Nov 17, 2026
885c291
refactor: isolate unbuild compatibility in `src/legacy`
danielroe Nov 17, 2026
16983cd
refactor!: make `transpileDir` internal and drop the `./rolldown` export
danielroe Nov 17, 2026
2c2e379
feat!: remove the implicit default `build` command
danielroe Nov 17, 2026
3c68dfb
refactor: share helpers in `src/utils.ts` and merge single-purpose mo…
danielroe Nov 17, 2026
e7858b6
fix: refuse a directory entry that would replace `types.d.mts`
danielroe Nov 17, 2026
d7047d9
fix: remove the output when a check after the bundle fails
danielroe Nov 17, 2026
6f29a2f
test: fold regression tests into their suites
danielroe Nov 17, 2026
7303e51
refactor: simplify the largest modules
danielroe Nov 17, 2026
fdcc181
fix: refuse a directory entry that emits `types.d.mts` at the output …
danielroe Nov 17, 2026
b9a5076
docs: add an architecture overview in CONTRIBUTING.md
danielroe Nov 17, 2026
30e08a9
chore: drop the unused `rolldown` dev dependency
danielroe Nov 17, 2026
a7b30c3
fix: avoid exponential backtracking in the dynamic import specifier r…
danielroe Nov 17, 2026
8f9b40b
docs: note that `src/transpile` only depends on `src/utils.ts`
danielroe Nov 17, 2026
38548c5
fix: refuse a bundled entry named `types` in any case
danielroe Nov 17, 2026
edfcd8c
fix: follow symlinks before checking that `outDir` is inside the module
danielroe Nov 17, 2026
c97b338
fix: keep runtime imports of a dot-prefixed output directory relative
danielroe Nov 17, 2026
ad1c0bc
test: fail fast when a process slot cannot be created
danielroe Nov 17, 2026
53a0518
fix: compare `outDir` with the real module root
danielroe Nov 17, 2026
0894a54
test: give the shared fixture hooks ten minutes on slow runners
danielroe Nov 17, 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
137 changes: 137 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
# Contributing

## Setup

`package.json` pins Node and pnpm in `devEngines`, and pnpm downloads them when they are missing.

```bash
pnpm install
pnpm dev:prepare
```

| Script | What it runs |
|---|---|
| `pnpm build` | `tsdown`, building this package into `dist` |
| `pnpm test` | the vitest suite (`pnpm vitest run` for one pass) |
| `pnpm test:types` | `vue-tsc` over the package and the example |
| `pnpm test:knip` | unused files, exports and dependencies |
| `pnpm test:pack` | packs the example and checks it with attw and publint |
| `pnpm lint` | ESLint |
| `pnpm nuxt-module-build` | the CLI from source, for example `pnpm nuxt-module-build build ./example` |

Pages in [`docs/`](./docs) are published on [nuxt.com](https://nuxt.com), so links between them use nuxt.com paths. Build messages link to headings of [`docs/upgrade-v2.md`](./docs/upgrade-v2.md) through `guide()` in `src/build/guide.ts`. A unit test checks that every linked heading exists.

## Architecture

The package has three entry points:

- **`src/cli.ts`** is the `nuxt-module-build` binary, also run as `nuxt build-module`. It has two subcommands, `build` and `prepare`.
- **`src/tsdown/index.ts`** exports `builder()`, the tsdown plugin that builds a module. This is how modules build: `tsdown` with `plugins: [builder()]`.
- **`src/index.ts`** exports `build`, `prepare` and the unbuild-compatible `defineBuildConfig`.

### Layout

| Directory | Contents |
|---|---|
| `src/commands/` | The CLI subcommands, plus `config-file.ts`, which finds the module's tsdown config and reads the `builder()` options from it. |
| `src/tsdown/` | The `builder()` plugin. `plugin.ts` creates it, and `setup.ts` turns the tsdown config into a build. It adds the plugins, hooks into tsdown's lifecycle, and handles watch mode. `externals.ts`, `unchanged.ts` and `report.ts` are the plugins and helpers that `setup.ts` uses. `build.ts` runs tsdown for `nuxt-module-build build`. |
| `src/build/` | The build itself, independent of tsdown's plugin API:<br>`options.ts` resolves `builder()` options.<br>`build.ts` resolves a `BuildPlan` and runs the steps before and after the bundle.<br>`loader.ts` imports module code and checks that Node can load it.<br>`package.ts` holds the `package.json` checks.<br>`types.ts` and `module-declarations.ts` write `types.d.mts` and the declarations `prepare` generates.<br>`aliases.ts` rewrites `#app` in declarations. |
| `src/transpile/` | `transpileDir()`, the internal rolldown plugin that transpiles a directory file by file. It transforms scripts with oxc and `.vue` files with `vue.ts`, compiles stylesheets with `stylesheets.ts`, emits declarations with `declarations.ts`, rewrites import specifiers with `specifiers.ts`, and resolves the tsconfig of each file with `tsconfig.ts`. It imports nothing outside the directory but `src/utils.ts`, so it can be extracted later. |
| `src/legacy/` | Compatibility with v1 and unbuild (see [Legacy code](#legacy-code)). |
| `src/utils.ts` | Path, file and regex helpers shared across directories. |

### `tsdown` with `builder()`

`builder()` acts in tsdown's `tsdownConfig` hook. `setupBuilder` then:

1. Refuses tsdown options that `builder()` sets itself, resolves the module root (following symlinks) and the output directory, and checks the published `package.json` paths.
2. Resolves the `builder()` options into a `ModuleConfig` (`src/build/options.ts`). When `.nuxt` is missing, it runs `prepare` first.
3. Resolves a `BuildPlan` (`resolveBuild` in `src/build/build.ts`), with these parts:
- the bundled entries (`src/module` and `entries`);
- the transpiled directories (`src/runtime` and directory entries);
- the tsconfigs for declarations;
- the module's self-reference paths;
- a cache key for `.vue` declarations.
4. Sets `entry`, `format`, `dts`, `clean` and `deps.neverBundle`. Adds `runtimeExternals` (bundled code imports runtime files from `dist` instead of inlining them), the declaration externals, replacements, and one `transpileDir()` per directory.

Then, once per build:

- **`build:prepare`** runs `prepareBuild`:
- the `build:before` hook;
- the check that module code loads with Node;
- emptying the output directory;
- the derived tsconfig that declaration generation reads.
- **During the bundle**, the bundled entries and each `transpileDir()` emit their files.
- **After writing**, `finishBuild` does the rest. Any failure removes the output directory, except in watch mode.
- Imports the built `module.mjs` to write `module.json`.
- Writes `types.d.mts`.
- Rewrites `#app` in declarations.
- Checks the package `imports` that the output uses.
- Runs the `build:done` hook.

In watch mode the output directory is kept, unchanged files aren't rewritten (`unchanged.ts`), and files a rebuild no longer emits are removed.

### `nuxt-module-build build`

`src/tsdown/build.ts` runs tsdown programmatically. With a tsdown config in the module root, it builds with that config and fails unless it uses `builder()`. Without one, it builds with `createBuilder()` and `loadLegacyModuleConfig`. That reads `build.config.*` or the `build` field of `package.json`, so a v1 module builds without a tsdown config.

### `nuxt-module-build prepare`

`src/commands/prepare.ts` does the following:

1. Loads the same options as a build.
2. Checks that module code loads with Node, then imports `src/module.ts` with `importModule`.
3. Runs `nuxt prepare` on the module root with that module installed.

That writes `.nuxt`, including:

- the tsconfigs of each context;
- `.nuxt/module-builder/types.d.mts`, which source exports point at;
- the declarations that resolve the module's own package name inside its type checks.

### Module code loads with Node

Nuxt 5, and a playground that loads the module from its sources, import `src/module.ts` with Node as written. Node strips types and resolves imports exactly as they are written. `findModuleCodeIssues` in `src/build/loader.ts` reports each import and each piece of syntax that breaks this, with its file, line, column and fix. `build`, `tsdown` and `prepare` all stop on these findings. Keep this check strict: code that passes it has to run under Node.

### Legacy code

`src/legacy/` holds what only v1 and unbuild users need:

- `build-config.ts` reads and translates `build.config.*` and the `build`/`unbuild` fields of `package.json`, and emulates the unbuild hooks.
- `define.ts` contains `defineBuildConfig` and its types.
- `package-paths.ts` explains v1 `package.json` paths such as `module.cjs`.

Core code doesn't import legacy types. The call sites are:

- `src/index.ts`
- `src/tsdown/build.ts`
- `src/commands/prepare.ts`
- `src/build/options.ts`
- `src/build/package.ts`

Their tests live in `test/legacy.spec.ts`. To drop unbuild compatibility, delete the directory and that spec, then fix the call sites.

## Tests

| Spec | Surface |
|---|---|
| `test/cli.spec.ts` | `nuxt-module-build build` and `prepare` |
| `test/builder.spec.ts` | `tsdown` with `builder()`, and tsconfig `references` |
| `test/watch.spec.ts` | `tsdown --watch` |
| `test/transpile-dir.spec.ts` | `transpileDir()` on its own |
| `test/legacy.spec.ts` | `build.config.*`, the `build` field, `defineBuildConfig` |
| `test/unit.spec.ts` | pure helpers |

Each e2e spec builds its fixtures in one `beforeAll`, in parallel, and its `it` blocks only read the results:

- `fixture()` in `test/utils.ts` copies `example/` (or another fixture) into a gitignored `.temp-*` directory, with files, `package.json` fields and tsconfig `paths` changed.
- `cli()`, `tsdown()` and `run()` start processes, and the number running at once is capped at one per CPU.

Add a case to an existing fixture when it doesn't conflict with that fixture's other cases, and create a new fixture only when it does. Name tests `it('should ...')`.

Coverage of the CLI processes:

```bash
NODE_V8_COVERAGE=/tmp/cov pnpm vitest run
pnpm dlx c8@10 report --temp-directory /tmp/cov --include 'src/**' --reporter text --all --src .
```
10 changes: 2 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Create a module from the [module starter](https://github.com/nuxt/starter/tree/m
npm create nuxt -- -t module my-module
```

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.
Building a module requires Node `^22.18.0 || ^24.11.0 || >=26.0.0`, with `tsdown` and `typescript` installed alongside `@nuxt/module-builder`. Apps that install a built module need Nuxt 3 or later.

## Documentation

Expand All @@ -35,19 +35,13 @@ Building a module requires Node `^22.18.0 || >=24.0.0`, with `tsdown` and `types
- [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)

For writing the module itself, read the [Nuxt Module Author Guide](https://nuxt.com/docs/guide/modules).

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

Pages in [`docs/`](./docs) are written for [nuxt.com](https://nuxt.com), so links between them use nuxt.com paths.
See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, the architecture and the tests.

## License

Expand Down
2 changes: 1 addition & 1 deletion docs/2.commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ You build a module with `tsdown`, which reads the [`builder()` plugin](/docs/gui
- `build` builds the module, with or without a `tsdown.config.ts`.
- `prepare` generates the `.nuxt` directory that types the module.

Name the subcommand every time. `nuxt-module-build` without a subcommand runs `build` and prints a warning.
Name the subcommand every time: `nuxt-module-build` without one prints its usage.

The Nuxt CLI runs the same subcommands as [`nuxt build-module`](/docs/api/commands/build-module), so `nuxt build-module build` is the same as `nuxt-module-build build`. To see how a module's scripts combine these commands, read [Develop and Publish](/docs/guide/modules/module-builder/develop-and-publish).

Expand Down
2 changes: 1 addition & 1 deletion docs/4.configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ An entry is either bundled into one file, like `src/module.ts`, or transpiled fi
| Option | Description |
|---|---|
| `input` | The entry file, relative to the module root. You can leave out the extension. |
| `name` | The output name. Defaults to `input` without `src/` and without its extension. |
| `name` | The output name. Defaults to `input` without `src/` and without its extension. It can't be `types`, as the build writes `dist/types.d.mts` itself. |

The build writes each bundled entry to `dist/<name>.mjs`, with its declarations in `dist/<name>.d.mts`. The entries in the example above produce `dist/utils.mjs` and `dist/kit.mjs`. Add each one to the `exports` of `package.json`, as described in [Exports](/docs/guide/modules/module-builder/exports#bundled-entries).

Expand Down
120 changes: 0 additions & 120 deletions docs/8.transpile-dir.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/cli/build-module/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ npx nuxt build-module build [ROOTDIR] [--cwd=<directory>] [--outDir=<directory>]
npx nuxt build-module prepare [ROOTDIR] [--cwd=<directory>]
```

The `build-module` command runs the `nuxt-build-module` binary that [`@nuxt/module-builder`](/docs/guide/modules/module-builder) installs in your module. It's the same CLI as `nuxt-module-build`, with two subcommands. Without a subcommand, it runs `build` and prints a warning.
The `build-module` command runs the `nuxt-build-module` binary that [`@nuxt/module-builder`](/docs/guide/modules/module-builder) installs in your module. It's the same CLI as `nuxt-module-build`, with two subcommands. Without a subcommand, it prints its usage.

## `build`

Expand Down
3 changes: 1 addition & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ navigation:

To build a module, you need:

- Node `^22.18.0 || >=24.0.0`.
- Node `^22.18.0 || ^24.11.0 || >=26.0.0`.
- `tsdown` and `typescript` (`^5.9.3 || ^6.0.0`), which are peer dependencies of `@nuxt/module-builder`.
- `nuxt`, which provides the `@nuxt/cli` that `nuxt-module-build prepare` runs.

Expand Down Expand Up @@ -104,5 +104,4 @@ The `dev:prepare` script in step 3 is for a module that you publish with pnpm or
- [TypeScript](/docs/guide/modules/module-builder/typescript): your module's `tsconfig.json`, its declarations, and the rules for module code.
- [Build Output](/docs/guide/modules/module-builder/output): the files in `dist`, and the size report.
- [Exports](/docs/guide/modules/module-builder/exports): subpath exports, including runtime components.
- [Transpiling a Directory](/docs/guide/modules/module-builder/transpile-dir): the `transpileDir` rolldown plugin.
- [Upgrading to v2](/docs/guide/modules/module-builder/upgrade-v2): moving a module from v1.
Loading
Loading