An Rsbuild plugin to emit declaration files for TypeScript which is built-in in Rslib.

Read Declaration files and lib.dts for more details.

Install:

npm add rsbuild-plugin-dts -D

Add plugin to rsbuild.config.ts:

// rsbuild.config.ts
import { pluginDts } from 'rsbuild-plugin-dts';

export default {
  plugins: [pluginDts()],
};

• Type: boolean | { tsconfigPath?: string; bundledPackages?: string[] }
• Default: false

Whether to bundle the declaration files.

If you want to bundle declaration files files, you should:

1. Install @microsoft/api-extractor as a development dependency, which is the underlying tool used for bundling declaration files.

npm add @microsoft/api-extractor -D

2. Set bundle to true.

pluginDts({
  bundle: true,
});

• Type: string
• Default: source.tsconfigPath

Configure a custom tsconfig.json file path for API Extractor to bundle declaration files. Relative paths are resolved from the project root.

When declaration bundling is enabled, TypeScript configuration is used in two stages:

• source.tsconfigPath is used to generate temporary declaration files in .rstack/declarations.
• bundle.tsconfigPath is used by API Extractor to analyze and bundle the temporary declaration files generated above.

By default, both stages use source.tsconfigPath. If you want API Extractor to use a separate TypeScript configuration, for example to adjust module resolution options such as paths, use the following configuration:

pluginDts({
  bundle: {
    tsconfigPath: './tsconfig.dts-bundle.json',
  },
});

• Type: string[]

Specifies the dependencies whose declaration files should be bundled. This configuration is passed to the bundledPackages option of @microsoft/api-extractor.

By default, rsbuild-plugin-dts determines externalized dependencies based on the following configurations.

• autoExternal configuration
• output.externals configuration

Direct dependencies (declared in package.json) that are not externalized will be automatically added to bundledPackages, and their declaration files will be bundled into the final output.

When the default behavior does not meet the requirements, you can explicitly specify the dependencies whose declaration files need to be bundled through bundle.bundledPackages. After setting this configuration, the above default behavior will be completely overwritten.

This is typically used for bundling transitive dependencies (dependencies of direct dependencies). For example, if the project directly depends on foo, and foo depends on bar, you can bundle both foo and bar's declaration files as follows:

pluginDts({
  bundle: {
    bundledPackages: ['foo', 'bar'],
  },
});

bundledPackages can be specified with the minimatch syntax, but will only match the declared direct dependencies in package.json.

• Type: string

The output directory of declaration files. The default value follows the priority below:

1. The distPath value of the plugin options.
2. The declarationDir value in the tsconfig.json file.
3. The output.distPath or output.distPath.root value of Rsbuild configuration.

pluginDts({
  distPath: './dist-types',
});

• Type: boolean
• Default: false

Whether to generate declaration files with building the project references. This is equivalent to using the --build flag with the tsc command. See Project References for more details.

When the project references are configured but the referenced project has not been built separately (for example, the source code of other projects is directly referenced in monorepo, but the corresponding declaration file is missing in the project), this option needs to be enabled to ensure that the declaration files of referenced projects can be generated correctly, thereby ensuring the integrity of the type system.

This option can only be used when bundle is false. When this option is enabled, declarationDir or outDir needs to be explicitly set in tsconfig.json to meet build requirements.

• Type: boolean
• Default: true

Whether to abort the build process when an error occurs during declaration files generation.

By default, type errors will cause the build to fail.

When abortOnError is set to false, the build will still succeed even if there are type issues in the code.

pluginDts({
  abortOnError: false,
});

• Type: string
• Default: '.d.ts'

The extension of the declaration file.

pluginDts({
  dtsExtension: '.d.mts',
});

When tsgo is enabled, if the project also enables build or emits declaration files with different extensions to the same directory, dtsExtension may not work correctly.

• Type: Record<string, string>
• Default: {}

Configure the path alias for declaration files.

The path aliases configured in alias should be resolved relative to the directory specified by compilerOptions.baseUrl in tsconfig.json. These aliases will be merged with compilerOptions.paths, and alias takes higher precedence.

In most cases, you don't need to use alias, but consider using it when you need to use path alias only in declaration files without wanting to affect JavaScript outputs. For example, map the declaration file of foo to ./compiled/foo.

pluginDts({
  alias: {
    foo: './compiled/foo',
  },
});

At this time, when redirect.path is enabled, the import path of foo in the declaration file will be redirected to ./compiled/foo.

- export * from 'foo';
+ export * from './compiled/foo';

• Type: boolean
• Default: true

Whether to automatically externalize dependencies of different dependency types and do not bundle them into the declaration file.

The default value of autoExternal is true, which means the following dependency types will not be bundled:

• dependencies
• optionalDependencies
• peerDependencies

And the following dependency types will be bundled:

• devDependencies

pluginDts({
  autoExternal: {
    dependencies: true,
    optionalDependencies: true,
    peerDependencies: true,
    devDependencies: false,
  },
});

• Type: string
• Default: undefined

Inject content into the top of each declaration file.

pluginDts({
  banner: '/** @banner */',
});

• Type: string
• Default: undefined

Inject content into the bottom of each declaration file.

pluginDts({
  footer: '/** @footer */',
});

• Type:

type DtsRedirect = {
  path?: boolean;
  extension?: boolean;
};

• Default:

const defaultRedirect = {
  path: true,
  extension: true,
};

Controls the redirect of the import paths of TypeScript declaration output files.

pluginDts({
  redirect: {
    path: true,
    extension: true,
  },
});

• Type: boolean
• Default: true

Whether to automatically redirect the import paths of TypeScript declaration output files.

• When set to true, Rslib will redirect the import path in the declaration output file to the corresponding relative path based on the compilerOptions.paths configured in tsconfig.json.

// `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }`
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.d.ts'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo'; // expected output './dist/utils/index.d.ts'

• When set to false, the original import path will remain unchanged.

• Type: boolean
• Default: true

Whether to automatically redirect the file extension of import paths based on the TypeScript declaration output files.

• When set to true, the file extension of the import path in the declaration file will be automatically completed or replaced with the corresponding JavaScript file extension that can be resolved to the corresponding declaration file. The extension of the declaration output file is related to the dtsExtension configuration.

// `dtsExtension` is set to `.d.mts`
import { foo } from './foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'

import { foo } from './foo.ts'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'

• When set to false, import paths will retain their original file extensions.

• Type: string
• Default: The resolved path of typescript from the project root

Specifies a custom absolute path to the TypeScript module entry.

If a project uses TypeScript 6 and you want to try TypeScript 7 for declaration generation, install both versions with npm aliases:

{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}

Then, configure the plugin to use TypeScript 7 through the @typescript/native alias:

import { fileURLToPath } from 'node:url';
import { pluginDts } from 'rsbuild-plugin-dts';

export default {
  plugins: [
    pluginDts({
      typescriptPath: fileURLToPath(import.meta.resolve('@typescript/native')),
    }),
  ],
};

• Type: boolean
• Default: true when TypeScript 7+ is detected, otherwise false

Whether to generate declaration files using native TypeScript.

When unset, Rslib enables this option automatically when TypeScript 7+ is detected.

npm add typescript@latest -D

To ensure consistency during local development, you need to install the corresponding VS Code Preview Extension and add the following setting to VS Code:

{
  "typescript.experimental.useTsgo": true
}

• Type: boolean
• Default: false

Whether to generate declaration files with isolatedDeclarations.

This option is currently experimental.

When enabled, rsbuild-plugin-dts uses Rspack's built-in SWC fast_dts capability to generate declaration files directly during the build.

pluginDts({
  isolated: true,
});

When enabling this option, we recommend also enabling isolatedDeclarations in tsconfig.json so TypeScript can surface code that does not satisfy the isolatedDeclarations constraints earlier.

{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}

By default, rsbuild-plugin-dts generates declaration files through the TypeScript Compiler API, and it can also generate declaration files by enabling tsgo. Unlike these two approaches, isolated is the fastest option and is suitable for scenarios that prioritize build performance.

Since isolated does not perform type checking during declaration generation, it is usually used together with another independent, high-performance type checking workflow. For example, in a monorepo project, you can use this option together with rslint --type-check:

• Daily builds: use isolated to quickly output declaration files when building each package.
• Global checks: run rslint --type-check in CI or pre-commit hooks to perform unified type checking when needed.

This preserves full type checking while reducing the cost of repeatedly running TypeScript type analysis, loading TypeScript or tsgo related packages, and loading native bindings during each package build, making the overall build pipeline lighter.

isolated generates declaration files based on the module dependency graph during the Rspack build. Only entry modules and modules referenced by entry modules will generate corresponding declaration files. If a file is not included in the build dependency graph, it will not automatically generate declaration files like TypeScript does. If you want declaration files to be generated for these files as well, add them to source.entry, or make sure they are referenced by an existing entry.

• isolated is currently only available when pluginDts is used through Rslib, because it requires Rslib's built-in RslibPlugin.
• isolated cannot be enabled together with typescriptPath.
• isolated cannot be enabled together with tsgo.
• isolated cannot be enabled together with build.
• When isolated is enabled, abortOnError cannot be set to false.

Please read the Contributing Guide.

MIT licensed.