#lib.dts

• Type:

type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
      alias?: Record<string, string>;
      tsgo?: boolean;
    }
  | boolean;

• Default: undefined
• CLI: --dts / --no-dts

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.

export default {
  lib: [
    {
      format: 'esm',
      dts: true,
    },
  ],
};

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

export default {
  lib: [
    {
      format: 'esm',
      dts: false,
    },
  ],
};

#Object type

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

#dts.bundle

• Type: boolean | { 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 dts.bundle to true.

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: true,
      },
    },
  ],
};

#dts.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, Rslib determines externalized dependencies based on the following configurations. For details, refer to Handle third-party dependencies.

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

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};

#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 or output.distPath.root value in the current lib configuration.

#Example

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};

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

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.

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

export default {
  lib: [
    {
      format: 'esm',
      dts: {
        abortOnError: false,
      },
    },
  ],
};

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

#dts.alias

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

Configure the path alias for declaration files.

dts.alias will be merged with compilerOptions.paths configured in tsconfig.json and dts.alias has a higher priority.

In most cases, you don't need to use dts.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.

export default {
  lib: [
    {
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};

#dts.tsgo

• Type: boolean
• Default: false

Whether to generate declaration files with tsgo, which can provide faster generation of declaration files, especially for large projects.

To enable this option, you need to:

1. Install @typescript/native-preview as a development dependency.

npm add @typescript/native-preview -D

2. Configure in the Rslib config file:

export default {
  lib: [
    {
      dts: {
        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:

{
  "typescript.experimental.useTsgo": true
}