\n\nAre you publishing a TypeScript project where consumers encounter type-checking errors like:\n\n```\nCannot find module 'some-package' or its corresponding type declarations.\n```\n\nWhen you compile with `tsc`, the emitted declaration files (`.d.ts` files) preserve imports exactly as written. So if your published types import from a `devDependency` or a private package (e.g. an internal monorepo package), those imports cannot be resolved by the consumer.\n\n```ts\n// dist/index.d.ts (generated by tsc)\nimport type { SomeType } from 'my-private-dependency' // ❌ consumers can't resolve this\n\nexport declare function myUtility(): SomeType\n```\n\nIf you can't move the dependency to `dependencies`, or you just want its types pulled directly into your published declarations, _dtsroll_ is for you.\n\n## What is dtsroll?\n\n_dtsroll_ is a TypeScript declaration (`.d.ts`) file bundler. It's zero-config and reads your `package.json` to determine how your types should be bundled.\n\n### What dtsroll does\n\n_dtsroll_ runs *after your build when `.d.ts` files have been emitted*, and works in-place to bundle them to their entry points.\n\nSince packages declared in `devDependencies` are not installed for the consumer, _dtsroll_ assumes any imports referencing them should be bundled, as they would otherwise be unresolvable.\n\nThe result is a single, clean `.d.ts` output that works for consumers without extra installs.\n\n```ts\n// dist/index.d.ts (after dtsroll)\ntype SomeType = {\n value: string\n}\n\nexport declare function myUtility(): SomeType\n```\n\n### Features\n\n- **Zero config** — Automatically finds entry points from `package.json`.\n- **Fixes missing-type errors** — Inlines types from `devDependencies` so consumers don't need them installed.\n- **Tree-shaken output** — Unused types are removed to keep files small.\n- **In-place** — Designed to run directly on your `dist` folder after compilation.\n\n
\n \n
\n\n## Install\n\n```bash\nnpm install --save-dev dtsroll\n```\n\n## Quick start\n\n### 1. Configure `package.json`\n\nPoint your `types` or `exports` to the final `.d.ts` file you want to publish.\n\n```jsonc\n{\n\t\"name\": \"my-package\",\n\t\"exports\": {\n\t\t\"types\": \"./dist/index.d.ts\", // dtsroll targets this\n\t\t\"default\": \"./dist/index.js\",\n\t},\n\t\"scripts\": {\n\t\t\"build\": \"tsc && dtsroll\",\n\t},\n}\n```\n\n### 2. Build\n\n```bash\nnpm run build\n```\n\nThat's it.\n\n> [!WARNING]\n> _dtsroll_ modifies files in-place—bundled source files are removed and entry files are overwritten with bundled output.\n> Use `--dry-run` first to see what it would change:\n>\n> ```bash\n> dtsroll --dry-run\n> ```\n\n## Behavior\n\n### Automatic configuration\n\nBy default, _dtsroll_ reads your `package.json` to determine which imports should be bundled and which should remain external. The recommended setup is to run _dtsroll_ without any configuration and let it infer the correct behavior based on your dependency declarations.\n\n| Dependency type | Action | Reason |\n| ---------------------- | ----------- | ----------------------------- |\n| `devDependencies` | Bundle | Consumers don't install these |\n| `dependencies` | Externalize | Consumers already have them |\n| `optionalDependencies` | Externalize | Consumers already have them |\n| `peerDependencies` | Externalize | Provided by the consumer |\n\nIf you have a `@types/*` package in `devDependencies` but the corresponding runtime package in `dependencies`, _dtsroll_ will recommend moving the types package to `dependencies`, as this can otherwise result in missing types for consumers.\n\n### Manual configuration\n\nIf your project doesn't have a `package.json` file, you can still manually specify the input files (which entry files to collapse the `imports` into), and which packages to externalize.\n\n### Subpath imports\n\n> [!WARNING]\n> Currently, _dtsroll_ mistakenly resolves and bundles [subpath imports](https://nodejs.org/api/packages.html#subpath-imports). Subpath imports are intended to be dynamic aliases controlled by the consumer. In a future breaking release, _dtsroll_ will likely externalize them to preserve this behavior.\n\n## Usage\n\n_dtsroll_ can be used in several ways.\n\n### CLI usage\n\n```bash\ndtsroll [flags] [...entry .d.ts files]\n```\n\nIf no entry files are provided, _dtsroll_ reads `package.json` to determine them.\n\n#### Flags\n\n| Flag | Alias | Description |\n| -------------- | ----- | ------------------------------------------------- |\n| `--dry-run` | `-d` | Show what would be bundled without writing files |\n| `--sourcemap` | `-s` | Generate source maps (`.d.ts.map` files) |\n| `--conditions` | `-C` | Resolution conditions for [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) (e.g. `production`) |\n| `--external` | `-e` | *(Only when no `package.json`)* Packages to externalize |\n\n#### Why use `--sourcemap`?\n\nWithout source maps, \"Go to Definition\" in VS Code lands you in bundled `.d.ts` files—often a flattened wall of generated types that's hard to navigate.\n\nWith `--sourcemap`, _dtsroll_ generates `.d.ts.map` files that map positions in the bundled output back to your original source files. This lets VS Code jump directly to the actual TypeScript implementation instead of the generated declarations.\n\nThis is especially useful for:\n- **Monorepos** — Navigate seamlessly across packages to real source\n- **Library authors** — Give consumers a better DX when exploring your types\n- **Anyone debugging types** — Understand types at their origin, not the emitted output\n\n> [!NOTE]\n> For source navigation to work, the original `.ts` source files must be available (either shipped with your package or present locally). If they're not, VS Code falls back to the `.d.ts` file.\n\n### Vite plugin\n\nIf you use [`unplugin-dts`](https://github.com/qmhc/unplugin-dts), _dtsroll_ will automatically bundle the emitted types immediately after generation:\n\n```ts\nimport { defineConfig } from 'vitest/config'\nimport dts from 'unplugin-dts/vite'\nimport { dtsroll } from 'dtsroll/vite'\n\nexport default defineConfig({\n plugins: [\n dts(),\n dtsroll()\n ]\n})\n```\n\n### Node API\n\n```ts\nimport { dtsroll } from 'dtsroll'\n\nconst result = await dtsroll({\n cwd: process.cwd(),\n dryRun: false,\n sourcemap: true // generates .d.ts.map files\n})\n\nif ('error' in result) {\n console.error(result.error)\n} else {\n // Warnings about non-portable shared chunk types (TS2742)\n for (const warning of result.warnings) {\n console.warn(warning)\n }\n}\n```\n\n## Related\n\n- [pkgroll](https://github.com/privatenumber/pkgroll) — Zero-config JS + DTS bundler\n","readmeFilename":"README.md"}
![](\"./.github/logo.webp\"){kind=logo}
\n ![](\"./.github/screenshot.webp\")
\n