rollup-plugin-dts

What is rollup-plugin-dts?

The rollup-plugin-dts package is a Rollup plugin that allows you to bundle TypeScript declaration files (.d.ts). It is particularly useful for library authors who want to distribute their TypeScript types along with their JavaScript code.

What are rollup-plugin-dts's main functionalities?

Bundle TypeScript Declaration Files

This feature allows you to bundle multiple TypeScript declaration files into a single .d.ts file. The code sample demonstrates how to configure Rollup to use the rollup-plugin-dts to bundle TypeScript declaration files from 'src/index.d.ts' to 'dist/index.d.ts'.

import dts from 'rollup-plugin-dts';

export default {
  input: 'src/index.d.ts',
  output: {
    file: 'dist/index.d.ts',
    format: 'es'
  },
  plugins: [dts()]
};

Other packages similar to rollup-plugin-dts

typescript

The TypeScript package itself can generate declaration files using the 'declaration' and 'declarationDir' options in the tsconfig.json file. However, it does not bundle them into a single file. This is a more basic approach compared to rollup-plugin-dts, which provides more advanced bundling capabilities.

dts-bundle

The dts-bundle package is another tool for bundling TypeScript declaration files. It is similar to rollup-plugin-dts but is not a Rollup plugin. It can be used as a standalone tool or integrated into build scripts. It offers similar functionality but may require more manual setup compared to the seamless integration provided by rollup-plugin-dts.

README

rollup-plugin-dts

This is a plugin that lets you roll-up your .d.ts definition files.

Usage

Install the package from npm:

$ npm install --save-dev rollup-plugin-dts

Add it to your rollup.config.js:

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;

NOTE A default import of the plugin using import dts from "rollup-plugin-dts"; is still supported for existing implementations of this package. However, a named import is suggested to avoid the error [!] TypeError: dts is not a function¹² in certain rollup config file implementations.

And then instruct typescript where to find your definitions inside your package.json:

  "types": "dist/my-library.d.ts",

NOTE that the plugin will automatically mark any external library (@types for example) as external, so those will be excluded from bundling.

Maintenance Mode

This project is in maintenance mode. That means there will be no more active feature development. There will still be occasional releases to maintain compatibility with future TypeScript releases. Pull Requests are always welcome, however reaction time on both Issues and PRs can be slow.

What to expect

While this plugin is fairly complete, it does not support all imaginable use-cases. In particular, the plugin works best with already existing .d.ts files generated by the typescript compiler from idiomatic code.

Working with .ts(x) or even .js(x) (when setting allowJs: true) does work, but is not recommended.

The plugin does its own import resolution through the typescript compiler, and usage together with other resolution plugins, such as node-resolve can lead to errors and is not recommended.

All external dependencies from node_modules are automatically excluded from bundling. This can be overridden using the respectExternal setting, but it is generally not recommended. While rollup of external @types generally works, it is not recommended.

Why?

Well, ideally TypeScript should just do all this itself, and it even has a proposal to do that. But there hasn’t been any progress in ~3 years.

Some projects, like rollup itself go the route of completely separating their public interfaces in a separate file.

Alternatives

• API Extractor
• dts-bundle-generator
• rollup-plugin-ts
• tsc-prog

See some discussions about some of these projects and their tradeoffs.

How does it work

License

The code is licensed under the copyleft LGPL-3.0. I have no intention to license this under any non-copyleft license.

Footnotes

1. StackOverflow thread of issue ↩

2. Github issue ↩

Changelog

6.0.1

Compatibility Notice:

This release lowers the minimum required node.js version to 16.

Fixes:

• Fix namespace declarations being exported as export { type T }.

Thank you:

Features, fixes and improvements in this release have been contributed by:

• @mithodin
• @curlykay9527