rollup-plugin-flat-dts

2.9.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that flattens TypeScript .d.ts declaration files into a single bundle, generating a merged type definition file. Current stable version 2.9.0 supports Rollup 2.79.1–5.0 and TypeScript 4.8.4–5.8. It differs from other .d.ts bundlers by flattening instead of merging, which imposes strict constraints: all exports are public (use @internal to mark internals), default exports only at top level, and no renamed re-exports. Ideal for libraries that want a single type file and can adhere to its limitations. Released roughly twice a year, tracking TypeScript minor versions.

Common errors

error The plugin is intended to be used as an output plugin, not a regular plugin ↓

cause Adding flatDts() to `plugins` array instead of inside `output.plugins`

fix

Move flatDts() to output.plugins array in rollup.config.js.

error Error: TypeScript compiler options 'module' must be set to 'System' for DTS flattening ↓

cause The plugin expects module system set to 'System' internally (ignored in output) but user config may conflict

fix

Ensure tsconfig compilerOptions does not force a different module system that conflicts; plugin overrides as needed.

error Error: Cannot find module 'rollup-plugin-flat-dts' ↓

cause Package not installed; or ESM import in CommonJS context

fix

Install: npm install --save-dev rollup-plugin-flat-dts. Ensure rollup.config is ESM or use dynamic import.

Warnings

gotcha Default exports only supported at top level in entry points ↓

fix Avoid default exports in nested modules; use named exports and re-export in index.

gotcha Exported symbols must be unique across the codebase ↓

fix Rename duplicate exports to be globally unique.

gotcha Re-exports with aliases (e.g., `export { Foo as Bar }`) are not supported ↓

fix Use direct exports or alias via separate declaration: `const Bar = Foo; export { Bar };`

gotcha Every export in every file becomes part of public API unless marked @internal ↓

fix Add `@internal` JSDoc tag to internal exports, or use `internal` option with glob patterns.

breaking Forces `resolveJsonModule: false` as JSON module imports unsupported by SystemJS ↓

fix Avoid importing JSON modules in your source; or use a different output format.

breaking Disables `verbatimModuleSyntax` option as incompatible with SystemJS target ↓

fix Do not set `verbatimModuleSyntax` in tsconfig; plugin overrides it.

Install

npm install rollup-plugin-flat-dts

yarn add rollup-plugin-flat-dts

pnpm add rollup-plugin-flat-dts

Imports

flatDts

wrong

const { flatDts } = require('rollup-plugin-flat-dts')

correct

import flatDts from 'rollup-plugin-flat-dts'

Default export; named export not available. CommonJS users must use default interop.

flatDts (type)
```
import type { FlatDtsOptions } from 'rollup-plugin-flat-dts'
```
Options type exported for TypeScript users; import via type-only import to avoid runtime overhead.

Quickstart

Rollup config producing a single .js and flattened .d.ts. Demonstrates typical setup with TypeScript plugin and the flatDts output plugin.

import commonjs from '@rollup/plugin-commonjs';
import nodeResolve from '@rollup/plugin-node-resolve';
import flatDts from 'rollup-plugin-flat-dts';
import ts from 'rollup-plugin-typescript2';

export default {
  input: './src/index.ts',
  plugins: [commonjs(), ts(), nodeResolve()],
  output: {
    format: 'esm',
    file: 'dist/index.js',
    plugins: [flatDts({ tsconfig: 'tsconfig.json' })],
  },
};