Skip to content
Merged
17 changes: 12 additions & 5 deletions docs/1.project-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ my-module/
│ └── server/ # server routes, middleware, and Nitro plugins
├── playground/ # a Nuxt app that installs the module
├── package.json
├── tsconfig.json
├── tsconfig.json # references the tsconfigs in .nuxt
├── tsconfig.module.json
└── tsdown.config.ts # the build configuration
```

Expand Down Expand Up @@ -225,16 +226,22 @@ To publish more entry points, such as `my-module/utils` or `my-module/components

## `tsconfig.json`

Your module's own `tsconfig.json` extends the `.nuxt/tsconfig.json` that `prepare` generates in the module root:
Your module's own `tsconfig.json` references the tsconfigs that `prepare` generates in the module's `.nuxt`, one for each part of the module, with `tsconfig.module.json` in place of the one for module code:

```json [tsconfig.json]
{
"extends": "./.nuxt/tsconfig.json",
"exclude": ["dist", "node_modules", "playground"]
"files": [],
"exclude": ["dist", "node_modules", "playground"],
"references": [
{ "path": "./tsconfig.module.json" },
{ "path": "./.nuxt/tsconfig.app.json" },
{ "path": "./.nuxt/tsconfig.server.json" },
{ "path": "./.nuxt/tsconfig.shared.json" }
]
}
```

[TypeScript](/docs/guide/modules/module-builder/typescript) describes this setup.
[TypeScript](/docs/guide/modules/module-builder/typescript) describes this setup, and `tsconfig.module.json`.

## `tsdown.config.ts`

Expand Down
8 changes: 5 additions & 3 deletions docs/2.commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ npx nuxt-module-build build [ROOTDIR] [--cwd=<directory>] [--outDir=<directory>]
4. Empty the output directory.
5. Bundle `src/module.ts` and any other [bundled entry](/docs/guide/modules/module-builder/configuration#bundled-entries) with tsdown.
6. Transpile `src/runtime/` and any other [directory entry](/docs/guide/modules/module-builder/configuration#directory-entries) file by file.
7. Generate the declarations of every entry and runtime file, with the [module's `tsconfig.json`](/docs/guide/modules/module-builder/typescript).
7. Generate the declarations of every entry and runtime file, each with the project of the [module's `tsconfig.json`](/docs/guide/modules/module-builder/typescript) that includes it.
8. Print the [size of the output](/docs/guide/modules/module-builder/output#size-report).
9. Load the built module to write `dist/module.json`, and write `dist/types.d.mts`.
10. Compare the paths in `package.json` with the files that the build produced.
Expand Down Expand Up @@ -95,13 +95,15 @@ npx nuxt-module-build prepare [ROOTDIR] [--cwd=<directory>]

`prepare` generates `.nuxt` in the module root. It runs `nuxt prepare` on the module root, as a Nuxt app with your module as its only module and with auto-imports disabled. It writes nothing to `dist`.

Your module's `tsconfig.json` extends the `.nuxt/tsconfig.json` that `prepare` generates. Your editor, your type check, and the declarations that the build generates then see the same types:
Your module's `tsconfig.json` references the tsconfigs that `prepare` generates, one for each part of the module. Your editor, your type check, and the declarations that the build generates then see the same types:

- `@nuxt/schema`.
- The `#app`, `#imports`, and `#build` aliases.
- Anything your module adds, such as its templates and its server routes.

`prepare` also writes `.nuxt/module-builder/types.d.mts`. This file re-exports `src/module.ts`, and adds the same [type augmentations](/docs/guide/modules/module-builder/project-structure#srcmodulets) as `dist/types.d.mts`. With [source exports](/docs/guide/modules/module-builder/develop-and-publish#source-exports), the root export's `types` condition points at it.
`prepare` also writes `.nuxt/module-builder/types.d.mts`. This file re-exports `src/module.ts`, and adds the same [type augmentations](/docs/guide/modules/module-builder/project-structure#srcmodulets) as `dist/types.d.mts`. With [source exports](/docs/guide/modules/module-builder/develop-and-publish#source-exports), the root export's `types` condition points at it, and the tsconfig for module code includes it.

In the app, server and shared tsconfigs, `prepare` resolves your module's own package name to declarations of module code, which it writes into `.nuxt/module-builder/declarations`. A declaration error there is a warning, which the build reports as an error.

### How `prepare` loads your module

Expand Down
2 changes: 1 addition & 1 deletion docs/3.develop-and-publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The [playground](/docs/guide/modules/module-builder/project-structure#playground
| pnpm, Yarn 4 | Your sources, with the `dist` paths in `publishConfig` | The playground runs your sources. See [Source exports](#source-exports). |
| npm, Yarn 3 and earlier, bun | `dist` | `tsdown --watch` rebuilds `dist`. See [Developing against `dist`](#developing-against-dist). |

Run `dev:prepare` after you install dependencies. Run it again when the types that it generates are out of date, such as after the module registers a new template or server route.
Run `dev:prepare` after you install dependencies. Run it again when the types that it generates are out of date, such as after the module registers a new template or server route. The module's own app, server and shared type checks see the types of module code as of the last `prepare`.

The build runs `prepare` on its own when `.nuxt` is missing. Keep `prepare` in `dev:prepare` anyway, so the module's types are in place before your editor or your type check needs them.

Expand Down
41 changes: 30 additions & 11 deletions docs/5.typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,45 @@ A module has two TypeScript setups: one for the module itself, and one for its p

## The module's `tsconfig.json`

The module root has a `tsconfig.json` of its own. It extends the `.nuxt/tsconfig.json` that [`nuxt-module-build prepare`](/docs/guide/modules/module-builder/commands#prepare) generates there:
[`nuxt-module-build prepare`](/docs/guide/modules/module-builder/commands#prepare) generates a `.nuxt` in the module root, with one tsconfig for each part of the module: `tsconfig.node.json` for `src/module.ts` and the files next to it, `tsconfig.app.json` for `src/runtime/`, `tsconfig.server.json` for `src/runtime/server/`, and `tsconfig.shared.json` for code that both the app and the server use. The module's own `tsconfig.json` references them, with a `tsconfig.module.json` of yours in place of the one for module code:

```json [tsconfig.json]
{
"extends": "./.nuxt/tsconfig.json",
"files": [],
"exclude": ["dist", "node_modules", "playground"],
"references": [
{ "path": "./tsconfig.module.json" },
{ "path": "./.nuxt/tsconfig.app.json" },
{ "path": "./.nuxt/tsconfig.server.json" },
{ "path": "./.nuxt/tsconfig.shared.json" }
]
}
```

```json [tsconfig.module.json]
{
"extends": "./.nuxt/tsconfig.node.json",
"compilerOptions": {
"erasableSyntaxOnly": true
},
"exclude": ["dist", "node_modules", "playground"]
"erasableSyntaxOnly": true,
"tsBuildInfoFile": "./.nuxt/tsconfig.module.tsbuildinfo"
}
}
```

This tsconfig covers both `src/module.ts` and `src/runtime/`. Your editor, your type check, and the declarations that the build generates all read it, so they see the same types.
Type-check the module with `vue-tsc -b --noEmit`. Each part is checked with the types it has in an app that installs the module, and the build generates each file's declarations with the project that includes it, so your editor, your type check, and `dist` see the same types.

The `.nuxt` in the module root types the module as Nuxt sees it when the module is installed alone. It uses the module's default options, and disables auto-imports. It's separate from the playground's `.nuxt`, which reflects the playground's configuration and any other modules that it installs.

- `erasableSyntaxOnly` makes the type check report the syntax that Node can't run in [module code](#module-code).
- `tsBuildInfoFile` keeps the build info that `vue-tsc -b` writes in `.nuxt`, next to that of the generated tsconfigs.
- `exclude` leaves out `playground`, so the playground's own tsconfig types its files. Add any other directory that isn't part of the module, such as `docs`.
- Options in the root's `compilerOptions`, such as `"types": ["youtube"]`, apply to every part. Keep `./.nuxt/tsconfig.app.json` itself in `references`.

`prepare` adapts the generated tsconfigs to a module. [Module tsconfig](/docs/guide/modules/module-builder/upgrade-v2#module-tsconfig) in the upgrade guide describes what it changes, and the errors that checking each part can report.

The generated tsconfigs set `allowImportingTsExtensions`, so relative imports with a `.ts` extension type-check without further settings.

The generated `.nuxt/tsconfig.json` sets `allowImportingTsExtensions`, so relative imports with a `.ts` extension type-check without further settings.
A `tsconfig.json` that extends `./.nuxt/tsconfig.json` also works, type-checked with `vue-tsc --noEmit`, but checks less. See [Extending .nuxt/tsconfig.json](/docs/guide/modules/module-builder/upgrade-v2#extending-nuxttsconfigjson).

## Module code

Expand Down Expand Up @@ -134,7 +153,7 @@ To type-check the module and the playground, run the type check once in each:
```json [package.json]
{
"scripts": {
"test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
"test:types": "vue-tsc -b --noEmit && cd playground && vue-tsc --noEmit"
}
}
```
Expand All @@ -158,13 +177,13 @@ The type check can report these errors:

## Monorepos

In a monorepo, give the module its own `tsconfig.json`, as shown above. Don't rely on a root tsconfig or on an app's `.nuxt` for it. Move any `compilerOptions` that the module relies on into it, such as `"types": ["youtube"]` for a global namespace. They then apply to the module's own type check and to its declarations.
In a monorepo, give the module its own `tsconfig.json` and `tsconfig.module.json`, as shown above. Don't rely on a root tsconfig or on an app's `.nuxt` for it. Copy into its `compilerOptions` the entries of the repository root's `types` that the module's `src` relies on, such as `"youtube"` for a global namespace, and leave out those only tests or other packages use, such as `"vitest/globals"`. They then apply to the module's own type check and to its declarations.

The tsconfig that covers your module might extend or reference another app's `.nuxt/tsconfig.json` instead. In that case, the build generates declarations with the module's `./.nuxt/tsconfig.json`, plus that tsconfig's own `compilerOptions`, and prints a note. See [Module tsconfig](/docs/guide/modules/module-builder/upgrade-v2#module-tsconfig) in the upgrade guide.

## Declarations

The build generates declarations from your module's own files, with the module's tsconfig:
The build generates declarations from your module's own files, each with the project that includes it:

- The module entry and every other bundled entry, with TypeScript. With `isolatedDeclarations`, it uses oxc instead.
- Every script in the runtime directory and in other directory entries, with TypeScript.
Expand Down Expand Up @@ -196,7 +215,7 @@ Build-time aliases, such as `#build/*`, `#internal/*`, and other paths into `.nu

### `isolatedDeclarations`

With `isolatedDeclarations: true` in the module's tsconfig, the module entry's declarations come from oxc. oxc is faster than TypeScript, but every export then needs an explicit type, including the module definition:
With `isolatedDeclarations: true` in the tsconfig for module code, the module entry's declarations come from oxc. oxc is faster than TypeScript, but every export then needs an explicit type, including the module definition:

```ts [src/module.ts]
import { defineNuxtModule } from '@nuxt/kit'
Expand Down
2 changes: 1 addition & 1 deletion docs/8.transpile-dir.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The plugin emits every file under `srcDir` under `outBase` in the build's output
- Sass files compile to `.css`.
- Test and story files are left out by default.

Scripts are transpiled with oxc, and keep their imports as written. Relative imports are the exception: they get the emitted extension. `.vue` files are transpiled with `vue-sfc-transformer`, stylesheets are processed as described in [Build Output](/docs/guide/modules/module-builder/output#runtime-files), and other files are copied. Declarations come from one TypeScript program that uses the nearest `tsconfig.json`.
Scripts are transpiled with oxc, and keep their imports as written. Relative imports are the exception: they get the emitted extension. `.vue` files are transpiled with `vue-sfc-transformer`, stylesheets are processed as described in [Build Output](/docs/guide/modules/module-builder/output#runtime-files), and other files are copied. Declarations come from one TypeScript program per tsconfig project: the nearest `tsconfig.json`, or the project in its `references` that includes the file.

By default, the plugin transpiles scripts with the `transform` from `rolldown/utils`. `rolldown` is an optional peer dependency of `@nuxt/module-builder`, so install it in your project, or pass a `transform` of your own. `builder()` passes the `transform` of the `rolldown` that `tsdown` installs, so a module that builds with `builder()` needs neither.

Expand Down
2 changes: 1 addition & 1 deletion docs/cli/build-module/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Builds the module into `dist` for publishing. When the module has a `tsdown.conf

## `prepare`

Generates `.nuxt` in the module root, which the module's `tsconfig.json` extends. It also writes the declarations that the root export's `types` condition points at while `package.json` points at the module's sources. See [`prepare`](/docs/guide/modules/module-builder/commands#prepare).
Generates `.nuxt` in the module root, whose tsconfigs the module's `tsconfig.json` references. It also writes the declarations that the root export's `types` condition points at while `package.json` points at the module's sources. See [`prepare`](/docs/guide/modules/module-builder/commands#prepare).

### Arguments

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ To add `@nuxt/module-builder` to an existing module, follow these steps:
```

4. Point the `exports` of `package.json` at your module, as described in [Project Structure](/docs/guide/modules/module-builder/project-structure#packagejson).
5. Create a `tsconfig.json` that extends `.nuxt/tsconfig.json`, as described in [TypeScript](/docs/guide/modules/module-builder/typescript).
5. Create a `tsconfig.json` that references the tsconfigs in `.nuxt`, and a `tsconfig.module.json` for module code, as described in [TypeScript](/docs/guide/modules/module-builder/typescript).

The `dev:prepare` script in step 3 is for a module that you publish with pnpm or Yarn 4. If you publish with npm, Yarn 3 or earlier, or bun, add `tsdown` before `nuxt prepare playground`. [Develop and Publish](/docs/guide/modules/module-builder/develop-and-publish#preparing-a-checkout) explains the difference.

Expand Down
Loading
Loading