Rsbuild plugin that supports emitting declaration files for TypeScript.
npm install rsbuild-plugin-dts

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:
``bash`
npm add rsbuild-plugin-dts -D
Add plugin to rsbuild.config.ts:
`ts
// rsbuild.config.ts
import { pluginDts } from 'rsbuild-plugin-dts';
export default {
plugins: [pluginDts()],
};
`
- Type: booleanfalse
- Default:
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.
`bash`
npm add @microsoft/api-extractor -D
2. Set bundle to true.
`js`
pluginDts({
bundle: true,
});
#### bundle.bundledPackages
- 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:
`js`
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.declarationDir
2. The value in the tsconfig.json file.
3. The output.distPath or output.distPath.root value of Rsbuild configuration.
`js`
pluginDts({
distPath: './dist-types',
});
- Type: booleanfalse
- Default:
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.
When this option is enabled, you must explicitly set declarationDir or outDir in tsconfig.json in order to meet the build requirements.
- Type: booleantrue
- Default:
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.
`js`
pluginDts({
abortOnError: false,
});
- Type: string'.d.ts'
- Default:
The extension of the declaration file.
`js`
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{}
- 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.
`js`
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.
`diff`
- export * from 'foo';
+ export * from './compiled/foo';
- Type: booleantrue
- Default:
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:
- dependenciesoptionalDependencies
- peerDependencies
-
And the following dependency types will be bundled:
- devDependencies
`js`
pluginDts({
autoExternal: {
dependencies: true,
optionalDependencies: true,
peerDependencies: true,
devDependencies: false,
},
});
- Type: stringundefined
- Default:
Inject content into the top of each declaration file.
`js`
pluginDts({
banner: '/* @banner /',
});
- Type: stringundefined
- Default:
Inject content into the bottom of each declaration file.
`js`
pluginDts({
footer: '/* @footer /',
});
- Type:
`ts`
type DtsRedirect = {
path?: boolean;
extension?: boolean;
};
- Default:
`ts`
const defaultRedirect = {
path: true,
extension: false,
};
Controls the redirect of the import paths of TypeScript declaration output files.
`js`
pluginDts({
redirect: {
path: true,
extension: false,
},
});
#### redirect.path
- Type: booleantrue
- Default:
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.
`tscompilerOptions.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: booleanfalse
- Default:
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.
`tsdtsExtension
// 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: booleanfalse
- Default:
Whether to generate declaration files with tsgo, which can provide faster generation of declaration files, especially for large projects.
> This feature is currently an experimental feature. Since tsgo is still in the experimental stage, there may be some bugs and unresolved issues or limitations. So, make sure to fully test it in your project before enabling this option.
To enable this option, you need to:
1. Install @typescript/native-preview as a development dependency.
`bash`
npm add @typescript/native-preview -D
> @typescript/native-preview requires Node.js 20.6.0 or higher.
2. Set tsgo to true.
`js`
pluginDts({
tsgo: true,
});
3. In order to ensure the consistency of local development, you need to install the corresponding VS Code Preview Extension and add the following configuration in the VS Code settings:
`json``
{
"typescript.experimental.useTsgo": true
}
Please read the Contributing Guide.