With dtsOnly: true, each entry resolves to its declaration and the build emits
no JavaScript. Entries may be source files, existing .d.ts files, or both:
oxc when compilerOptions.isolatedDeclarations is enabled.
tsgo when typescript exposes Program.prototype.getDeclarationEmit, or
when TypeScript 7.0 is installed (deprecated, see below).
tsc otherwise.
Automatic selection only inspects typescript and never selects tsrs.
Selecting tsgo explicitly requires TypeScript 7.1 or later, or the
deprecated TypeScript 7.0 backend below.
[!WARNING]
With TypeScript 7.0, tsgo falls back to running the tsgo CLI. This backend
is deprecated and will be removed in the next minor; upgrade to TypeScript
7.1 or later. It does not support custom languages, and among the tsgo.*
options only tsgo.path (the executable to run) applies.
generator also accepts an object implementing the exported Generator
interface.
dts({ generator: 'oxc',})
Options
General
Option
Description
Default
generator
Built-in generator name or a custom Generator implementation.
Inferred
tsc
Options for the built-in tsc generator.
{}
entry
Glob or globs filtering which Rolldown entries emit declarations. Supports ! negation and paths relative to cwd.
All Rolldown entries
cwd
Base directory for config discovery, globs, and relative paths.
tsc.*, oxc.*, tsgo.*, and tsrs.* apply only to their respective
generators.
entry filters Rolldown entries. It never adds declarations for files that
are not entries. For example, to skip declarations for icon entries:
dts({ entry: ['src/**/*.ts', '!src/icons/**'],})
entry cannot be combined with dtsOnly. In a declaration-only build, list the
files in Rolldown input instead.
cjsDefault only changes the emitted export syntax. It does not enable
CommonJS-style declaration input.
TypeScript (tsc)
Option
Description
Default
tsc.build
Use TypeScript build mode and follow project references.
false
tsc.incremental
Persist build outputs, including .tsbuildinfo, to disk.
Enabled by the matching tsconfig options
tsc.parallel
Run tsc or vue-tsc in a separate process.
false
tsc.eager
Load every file listed by tsconfig.json.
false
tsc.newContext
Use an isolated compiler cache instead of the shared context.
false
tsc.vue
Register the built-in Vue integration using vue-tsc.
Top-level build, incremental, parallel, eager, newContext, and vue are
deprecated. Use tsc.* instead.
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. tsc.vue: true is the
preconfigured Vue shortcut.
This API is experimental and may change.
Oxc
Oxc generates declarations from each source file independently. Your code must
be compatible with isolatedDeclarations, including explicit type annotations
where required for exported declarations.
Option
Description
Default
oxc.stripInternal
Omit declarations marked with /** @internal */.
compilerOptions.stripInternal
sourcemap
Generate .d.ts.map files so editors can navigate from declarations to the original source.
Experimental. Requires typescript@7.1.0-beta or a compatible version and a
tsconfig.json.
Option
Description
Default
tsgo.moduleUrl
File URL of the TypeScript package that provides the Go API.
import.meta.resolve('typescript')
tsgo.path
Custom API server executable, passed as tsserverPath.
Provided by the selected package
tsgo.runExternalCode
Allow execution of content mappers configured in tsconfig.
false
tsgo.vfs
Supply transformed source code through a virtual filesystem.
false
The plugin's current tsgo implementation reads compiler settings from the
config file; tsconfigRaw and compilerOptions do not override them.
Declaration maps require compilerOptions.declarationMap: true in the config
file; setting only the plugin's sourcemap: true produces a warning.
With tsgo.vfs: true, source transforms must run before the dts transform hook.
Non-Volar custom languages also require a toTsFilename mapping.
Volar integrations, including tsc.vue, require tsc.
Extensions declared by content mappers (including inherited tsconfig settings)
are recognized automatically; customLanguages is not needed. Content mappers
read files from disk and cannot be combined with tsgo.vfs. If you also emit
JavaScript, use your framework's Rolldown plugin to transform these source files.
tsrs
Highly experimental; only the latest tsrs release is supported. Accepts the
same options as TypeScript Go under tsrs.* (moduleUrl defaults to
import.meta.resolve('tsrs')).
Vite
Exclude generated declarations from Oxc transformation. Because oxc.exclude
replaces Vite's default exclusions, keep JavaScript files excluded as well:
Declaration bundling requires an ESM Rolldown output. The cjs output format is
not supported. For CommonJS packages, build the JavaScript output separately
and use dtsOnly 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.