rollup-plugin-dts: bundling your TypeScript declarations into one file

One declaration file instead of a folder of them

The problem is narrow and the solution is narrower. A TypeScript library built normally emits a declaration file per source file, and a consumer then has to follow a tree of relative imports inside the published package to find a type. The plugin bundles those declarations into one file, so the package ships a single types entry. The readme is candid about why it exists, saying that ideally TypeScript should do all this itself and that there is a proposal to that effect, but that there has been no progress in around three years. Some projects take the other route, with rollup itself named as an example of separating the public interface completely into a separate file. The alternatives listed are API Extractor, dts-bundle-generator, rollup-plugin-ts and tsc-prog, and the readme links to issues and discussions comparing their tradeoffs rather than claiming the field is settled. The plugin itself is a Rollup plugin, so it runs inside a build you already have, and it does its own import resolution through the TypeScript compiler, which is why the documentation warns against combining it with other resolution plugins such as node-resolve.

Wiring it into a rollup configuration

The usage section shows the whole integration and it is short. You install the package from npm as a development dependency, then add the plugin to your rollup config:

import { dts } from "rollup-plugin-dts";

const config = [
  // …
  {
    input: "./my-input/index.d.ts",
    output: [{ file: "dist/my-library.d.ts", format: "es" }],
    plugins: [dts()],
  },
];

export default config;

The input is the entry declaration file, the output is a single .d.ts in the dist directory, and the plugin does the rest. There is one migration note that matters more than it looks. A default import of the plugin is still supported for existing implementations, but a named import is suggested, because in certain Rollup config file implementations the default import produces the error that the plugin is not a function. If you are upgrading an existing configuration and start seeing that error, the fix is to change the import style rather than to change versions. You then point TypeScript at the bundled file in your package manifest with a types entry naming the dist file, and the plugin will automatically mark any external library as external so those are excluded from the bundle.

The options, and what each one changes

There are five options and each has a specific purpose. The sourcemap option enables detailed sourcemaps for go-to-definition support, which loads .d.ts.map files and captures the declaration map for .ts inputs so an editor can navigate to the original source, and it also requires the output sourcemap option to be set in the Rollup configuration. The tsconfig option takes a path to a configuration file, defaulting to finding the nearest one. The compilerOptions option passes TypeScript compiler options directly, which is what you use for path mapping, with the example given setting a base URL and a path alias. The respectExternal option stops the plugin from automatically treating node_modules as external, and the includeExternal option bundles types from named external packages instead. The defaults are conservative, with respectExternal set to false and includeExternal empty, and the documentation is blunt that overriding the external handling is generally not recommended, and that while rolling up external types packages often works, it is not recommended.

TypeScript 7, and the compatibility package that bridges it

The TypeScript 7 section describes a problem worth understanding. TypeScript 7.0, the native compiler, does not ship a compiler API, and this plugin relies on one. The documented workaround is to install an additional compatibility package that provides the TypeScript 6 API:

npm install --save-dev @typescript/typescript6

The plugin uses the API from your own typescript package when it provides one, covering TypeScript 4.5 through 6.x, and falls back to the compatibility package otherwise. In that case the declaration files are parsed and emitted with TypeScript 6 language behaviour, which the documentation says is identical for declaration output. The note about the future is that once TypeScript 7.1 and later ship a new compiler API, a future release of the plugin will support it directly. There is a second consequence of the same problem, which is that the public types of the plugin reference the typescript package, and TypeScript 7 does not currently provide those, so a file that imports the plugin, such as a Rollup config written in TypeScript, can raise a spurious error. The documented fix is to enable the skipLibCheck option in the TypeScript configuration.

Maintenance mode, and the cases the plugin will not handle

The maintenance section is short and unambiguous. The project is in maintenance mode, meaning there will be no more active feature development, though there will still be occasional releases to maintain compatibility with future TypeScript releases, and pull requests are always welcome with the caveat that the reaction time on issues and pull requests can be slow. The expectations section then lists where the plugin stops working well. It works best with existing .d.ts files generated by the TypeScript compiler from idiomatic code, and while working with .ts or .tsx files, or even .js and .jsx with allowJs enabled, does work, it is not recommended. All external dependencies from node_modules are excluded by default. And the section on a shared declaration chunk problem is the most technical part of the documentation. When a bundled entry exposes a type that came from a private shared chunk, downstream declaration compiles can fail with the TS2742 error, which is part of a broader TypeScript declaration portability problem, and the plugin tries to rewrite that path through an entry that already re-exports the type publicly. What it does not do is invent new public exports, so if no public entry re-exports the shared type, the plugin emits a warning and the package should re-export the type explicitly.

Editorial conclusion

rollup-plugin-dts is a good fit for a library author who wants to publish a single types entry rather than a directory of declaration files, and who is already building with Rollup, since the plugin plugs into the existing configuration. It is the wrong tool if you publish types by shipping your compiled declarations as they are, because the problem it solves does not exist for you, and it is the wrong tool if you need the bundle to include types from node_modules, because the default is to exclude them and the documentation says overriding that is not recommended. It is also the wrong tool if you are on TypeScript 7 and do not want an extra package, since the compiler there has no API and the plugin needs a compatibility package. Before adopting it, read the expectations section, because the plugin is explicit that it works best with declaration files already generated from idiomatic TypeScript, and note that the project is in maintenance mode. The licence is LGPL-3.0, the last push was on 2026-10-19, and the package version is 6.5.1.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. README
4. Swatinem/rollup-plugin-dts on GitHub