close
Rslib
Guide
Config
Guide
Config

lib.dts

  • Type:
type Dts =
  | {
      bundle?: boolean;
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
    }
  | boolean;
  • Default: undefined

Configure the generation of the TypeScript declaration files.

Boolean type

Declaration files generation is an optional feature, you can set dts: true to enable bundleless declaration files generation.

rslib.config.ts
1export default {
2  lib: [
3    {
4      format: 'esm',
5      dts: true,
6    },
7  ],
8};

If you want to disable declaration files generation, you can set dts: false or do not specify the dts option.

rslib.config.ts
1export default {
2  lib: [
3    {
4      format: 'esm',
5      dts: false,
6    },
7  ],
8};

Object type

If you want to customize the declaration files generation, you can set the dts option to an object.

dts.bundle

  • Type: boolean
  • Default: false

Whether to bundle the declaration files.

Example

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
yarn
pnpm
bun
npm add @microsoft/api-extractor -D
  1. Set dts.bundle to true.
rslib.config.ts
1export default {
2  lib: [
3    {
4      format: 'esm',
5      dts: {
6        bundle: true,
7      },
8    },
9  ],
10};

Handle third-party packages

When we bundle declaration files, we should specify which third-party package types need to be bundled, refer to the Handle Third-Party Dependencies documentation for more details about externals related configurations.

dts.distPath

  • Type: string

The output directory of declaration files.

Default value

The default value follows the priority below:

  1. The dts.distPath value in the current lib configuration.
  2. The declarationDir value in the tsconfig.json file.
  3. The output.distPath.root value in the current lib configuration.

Example

rslib.config.ts
1export default {
2  lib: [
3    {
4      format: 'esm',
5      dts: {
6        distPath: './dist-types',
7      },
8    },
9  ],
10};

dts.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.

NOTE

When this option is enabled, you must explicitly set declarationDir or outDir in tsconfig.json in order to meet the build requirements.

dts.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 like below, the build will still succeed even if there are type issues in the code.

rslib.config.ts
1export default {
2  lib: [
3    {
4      format: 'esm',
5      dts: {
6        abortOnError: false,
7      },
8    },
9  ],
10};
WARNING

When this configuration is disabled, there is no guarantee that the type files will be generated correctly.

dts.autoExtension

  • Type: boolean
  • Default: false

Whether to automatically set the declaration file extension based on the format option.

Default extension

By default that when dts.autoExtension is false, the declaration file extension will be .d.ts.

When dts.autoExtension is set to true, the declaration file extension will be:

  • .d.ts with esm format and .d.cts with cjs format when type: module in package.json.

  • .d.ts with cjs format and .d.mts with esm format when type: commonjs or no type field in package.json.

NOTE

It follows the same logic as lib.autoExtension, but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.

ON THIS PAGE