rolldown-plugin-dts

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

Generator	Use it for	Requirement
tsc	Full TypeScript compatibility, Vue, and Volar languages	TypeScript 5.x or 6.x
oxc	Fast generation for isolated declarations	Code compatible with isolatedDeclarations
tsgo	Experimental TypeScript 7 builds	TypeScript 7 or @typescript/native-preview

When generator is omitted, the plugin selects:

• oxc when compilerOptions.isolatedDeclarations is enabled.
• tsgo when TypeScript 7 is installed as typescript.
• tsc otherwise.

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

dts({
  generator: 'oxc',
})

Options

General

Option	Description	Default
generator	Declaration generator: tsc, oxc, or tsgo.	Inferred
entry	Glob or globs selecting files to emit. Supports ! negation and paths relative to cwd.	Rolldown entries
cwd	Base directory for config discovery, globs, and relative paths.	process.cwd()
dtsInput	Treat entry files as existing declarations.	false
emitDtsOnly	Remove non-declaration chunks from the output.	false
tsconfig	Config path; true discovers one and false disables loading.	Nearest tsconfig.json
tsconfigRaw	Raw config values merged over the loaded config.	{}
compilerOptions	Compiler options merged over the loaded config.	{}
sourcemap	Emit .d.ts.map files.	declarationMap
resolver	Resolve declaration imports with oxc or tsc.	oxc
cjsDefault	Convert a single default export to export =.	false
sideEffects	Mark declaration modules as having side effects.	false
logger	Logger implementing info, warn, and error.	console

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)

Option	Description	Default
build	Use TypeScript build mode and follow project references.	false
incremental	Persist build outputs, including .tsbuildinfo, to disk.	Enabled by the matching tsconfig options
vue	Register the built-in Vue integration using vue-tsc.	false
parallel	Run tsc or vue-tsc in a separate process.	false
eager	Load every file listed by tsconfig.json.	false
newContext	Use an isolated compiler cache instead of the shared context.	false
emitJs	Generate declarations for JavaScript files with JSDoc types.	allowJs or checkJs

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' },
    ],
  },
}

Limitations

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

The following declaration input cannot be bundled:

• CommonJS export assignments such as export = value.
• CommonJS import aliases such as import value = require('package').
• Script-style ambient declarations, such as declare module 'package' { ... } or unexported top-level declare statements. Bundled declaration chunks are always modules, which would change the meaning of these declarations.

Mark dependencies that use unsupported declaration syntax 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