rolldown-plugin-dts

A Rolldown plugin that generates and bundles TypeScript declaration files.

Install

Requires Rolldown 1.2.0 or later and Node.js ^22.18.0 || ^24.11.0 || >=26.0.0.

npm i -D rolldown-plugin-dts

Install the compiler required by your generator:

npm i -D typescript@^6              # tsc
npm i -D @typescript/native-preview # tsgo, unless TypeScript 7 is installed

Oxc is provided by Rolldown and needs no additional dependency.

Usage

// rolldown.config.ts
import { defineConfig } from 'rolldown'
import { dts } from 'rolldown-plugin-dts'

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

See rolldown.config.ts for the project's own setup.

Generators

When generator is omitted, the plugin selects:

1. oxc when compilerOptions.isolatedDeclarations is enabled.
2. tsgo when TypeScript 7 is installed as typescript.
3. tsc otherwise.

Volar-based custom languages always require tsc. The tsgo generator does not support custom languages.

dts({
  generator: 'oxc',
})

Options

General

entry may include files that are not Rolldown entry points:

dts({
  entry: ['src/**/*.ts', '!src/icons/**'],
})

cjsDefault only changes the emitted export syntax. It does not enable CommonJS-style declaration input.

TypeScript (tsc)

incremental applies to build mode. When disabled, build outputs stay in memory.

To invalidate a file in the shared compiler cache:

import {
  globalContext,
  invalidateContextFile,
} from 'rolldown-plugin-dts/tsc-context'

invalidateContextFile(globalContext, 'src/foo.ts')

Custom languages

customLanguages registers non-standard source files such as Vue or Astro. Volar integrations must provide both volarTypeScript and createVolarPlugins; they require the tsc generator. vue: true is the preconfigured Vue shortcut.

This API is experimental and may change.

Oxc

oxc accepts IsolatedDeclarationsOptions. Use the top-level sourcemap option for declaration maps.

dts({
  generator: 'oxc',
  oxc: {
    stripInternal: true,
  },
})

TypeScript Go

tsgo is experimental and requires a tsconfig.json. It reads compiler options from that file, so tsconfigRaw and compilerOptions are ignored.

dts({
  generator: 'tsgo',
  tsgo: {
    path: '/path/to/tsgo',
  },
})

Vite

Exclude generated declarations from Oxc transformation. Because oxc.exclude replaces Vite's default exclusions, keep JavaScript files excluded as well:

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  oxc: {
    exclude: [/\.js$/, /\.d\.[cm]?ts$/],
  },
})

Code splitting

Declaration chunk names must end in .d:

export default {
  codeSplitting: {
    groups: [
      { test: /foo.*\.d\.[cm]?ts$/, name: 'shared.d' },
      { test: /foo/, name: 'shared' },
    ],
  },
}

CommonJS

Declaration bundling requires an ESM Rolldown output. For CommonJS packages, build the JavaScript output separately and use emitDtsOnly for a second declaration-only build.

The plugin expects ESM-style declaration input. Syntax such as export = or import x = require('x') may not bundle correctly. If it comes from a dependency, mark that dependency as external.

Credits

Inspired by rollup-plugin-dts, with an independent implementation. Its MIT-licensed test suite is used with permission.

Sponsors

License

MIT License © 2025-PRESENT Kevin Deng