Rsbuild-plugin-dts NPM

rsbuild-plugin-dts

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

Using in Rslib

Read Declaration files and lib.dts for more details.

Using in Rsbuild

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()],
};

Options

bundle

Type: boolean
Default: false

Whether to bundle the declaration files.

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

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

npm add @microsoft/api-extractor -D

Set bundle to true.

pluginDts({
  bundle: true,
});

distPath

Type: string

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

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

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

build

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 this option is enabled, you must explicitly set declarationDir or outDir in tsconfig.json in order to meet the build requirements.

abortOnError

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,
});

dtsExtension

Type: string
Default: '.d.ts'

The extension of the declaration file.

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

autoExternal

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,
  },
});

banner

Type: string
Default: undefined

Inject content into the top of each declaration file.

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

footer

Type: string
Default: undefined

Inject content into the bottom of each declaration file.

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

redirect

Type:

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

Default:

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

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

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

redirect.path

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.

redirect.extension

Type: boolean
Default: false

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

When set to true, the import paths in declaration files will be redirected to the corresponding JavaScript extension which can be resolved to 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, the file extension will remain unchanged from the original import path in the rewritten import path of the output file (regardless of whether it is specified or specified as any value).