> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# lib.dts

- **Type:**

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

- **Default:** `undefined`
- **CLI:** `--dts` / `--no-dts`
- **Top-level config:** Supported

Configure the generation of the TypeScript declaration files.

A top-level `dts` value is inherited by all `lib` items, but a `dts` value in a `lib` item takes precedence.

:::warning
When multiple `lib` items are present, using top-level `dts` may cause conflicting file writes or deletions during declaration generation, so configure `dts` on a specific `lib` item instead.
:::

## Boolean type

Declaration files generation is an optional feature, you can set `dts: true` to enable [bundleless declaration files](/guide/advanced/dts.md#bundleless-declaration-files) generation.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: true, // [!code highlight]
    },
  ],
};
```

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

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: false, // [!code highlight]
    },
  ],
};
```

## Object type

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

### dts.bundle

- **Type:** `boolean | { tsconfigPath?: string; bundledPackages?: string[] }`
- **Default:** `false`

Whether to bundle the declaration files.

If you want to [bundle declaration files](/guide/advanced/dts.md#bundle-declaration-files), you should:

1. Install [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) as a development dependency, which is the underlying tool used for bundling declaration files.


```sh [npm]
npm add @microsoft/api-extractor -D
```

```sh [yarn]
yarn add @microsoft/api-extractor -D
```

```sh [pnpm]
pnpm add @microsoft/api-extractor -D
```

```sh [bun]
bun add @microsoft/api-extractor -D
```

```sh [deno]
deno add npm:@microsoft/api-extractor -D
```

2. Set `dts.bundle` to `true`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        bundle: true,
      },
    },
  ],
};
```

::: note Usage limitations

Rslib uses API Extractor to bundle declaration files, so there may be some limitations caused by API Extractor's static analysis. For example, complex re-export chains, certain destructuring syntax, special declaration files generated by dependencies, or exports that cannot be resolved may cause errors like `Internal Error: Unable to analyze the export ...`. In this case, we recommend disabling `dts.bundle` and using bundleless declaration output.

:::

#### dts.bundle.tsconfigPath

- **Type:** `string`
- **Default:** [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath)

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](/config/rsbuild/source.md#sourcetsconfigpath) is used to generate temporary declaration files in `.rstack/declarations`.
- `dts.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:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        bundle: {
          tsconfigPath: './tsconfig.dts-bundle.json',
        },
      },
    },
  ],
};
```

#### dts.bundle.bundledPackages

- **Type:** `string[]`

Specifies the dependencies whose declaration files should be bundled. This configuration is passed to the [bundledPackages](https://api-extractor.com/pages/configs/api-extractor_json/#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](/guide/advanced/third-party-deps.md).

- [output.autoExternal](/config/rsbuild/output.md#outputautoexternal) configuration
- [output.externals](/config/rsbuild/output.md#outputexternals) 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:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        // [!code highlight:3]
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};
```

::: note
`bundledPackages` can be specified with the [minimatch](https://www.npmjs.com/package/minimatch) syntax, but will only match the declared direct dependencies in `package.json`.
:::

### 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](/config/rsbuild/output.md#outputdistpath) or [output.distPath.root](/config/rsbuild/output.md#outputdistpath) value in the current lib configuration.

#### Example

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      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](https://www.typescriptlang.org/docs/handbook/project-references.html) 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.

::: note

- This option can only be used when [dts.bundle](/config/lib/dts.md#dtsbundle) is `false`.
- When this option is enabled, `declarationDir` or `outDir` needs to be explicitly set in `tsconfig.json` to meet 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.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        abortOnError: false,
      },
    },
  ],
};
```

::: 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](/config/lib/format.md) 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

1. It follows the same logic as [lib.autoExtension](/config/lib/auto-extension.md), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.

2. Type declaration import extensions are controlled by the [redirect.dts.extension](/config/lib/redirect.md#redirectdtsextension) configuration.

3. When [dts.tsgo](/config/lib/dts.md#dtstsgo) is enabled, if the project also enables [dts.build](/config/lib/dts.md#dtsbuild) or emits declaration files with different extensions to the same directory, `dts.autoExtension` may not work correctly.

:::

### dts.alias

- **Type:** `Record<string, string>`
- **Default:** `{}`

Configure the path alias for declaration files.

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

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

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // [!code highlight:5]
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};
```

At this time, when [redirect.dts.path](/config/lib/redirect.md#redirectdtspath) is enabled, the import path of `foo` in the declaration file will be redirected to `./compiled/foo`.

```diff title="index.d.ts"
- export * from 'foo';
+ export * from './compiled/foo';
```

### dts.typescriptPath

- **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](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6.0):

```json title="package.json"
{
  "devDependencies": {
    "@typescript/native": "npm:typescript@^7.0.2",
    "typescript": "npm:@typescript/typescript6@^6.0.2"
  }
}
```

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

```ts title="rslib.config.ts"
import { fileURLToPath } from 'node:url';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      dts: {
        typescriptPath: fileURLToPath(
          import.meta.resolve('@typescript/native'),
        ),
      },
    },
  ],
});
```

### dts.tsgo

- **Type:** `boolean`
- **Default:** `true` when TypeScript 7+ is detected, otherwise `false`

Whether to generate declaration files using [native TypeScript](https://github.com/microsoft/typescript-go).

When unset, Rslib enables this option automatically when TypeScript 7+ is detected. When [dts.typescriptPath](#dtstypescriptpath) is configured, Rslib determines whether to enable `tsgo` automatically based on the resolved TypeScript version.


```sh [npm]
npm add typescript@latest -D
```

```sh [yarn]
yarn add typescript@latest -D
```

```sh [pnpm]
pnpm add typescript@latest -D
```

```sh [bun]
bun add typescript@latest -D
```

```sh [deno]
deno add npm:typescript@latest -D
```

To ensure consistency during local development, you need to install the corresponding [VS Code Preview Extension](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) and add the following setting to VS Code:

```json title=".vscode/settings.json"
{
  "typescript.experimental.useTsgo": true
}
```

### dts.isolated

- **Type:** `boolean`
- **Default:** `false`

Whether to generate declaration files with `isolatedDeclarations`.

:::tip

This option is currently experimental.

:::

When enabled, Rslib uses Rspack's built-in SWC fast\_dts capability to generate declaration files directly during the build.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        isolated: true, // [!code highlight]
      },
    },
  ],
};
```

When enabling this option, we recommend also enabling [isolatedDeclarations](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations) in `tsconfig.json` so TypeScript can surface code that does not satisfy the `isolatedDeclarations` constraints earlier.

```json title="tsconfig.json"
{
  "compilerOptions": {
    "isolatedDeclarations": true
  }
}
```

:::info Usage constraints

- `dts.isolated` cannot be enabled together with [dts.typescriptPath](/config/lib/dts.md#dtstypescriptpath).
- `dts.isolated` cannot be enabled together with [dts.tsgo](/config/lib/dts.md#dtstsgo).
- `dts.isolated` cannot be enabled together with [dts.build](/config/lib/dts.md#dtsbuild).
- When `dts.isolated` is enabled, [dts.abortOnError](/config/lib/dts.md#dtsabortonerror) cannot be set to `false`.

:::

#### Use cases

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

Since `dts.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`](https://rslint.rs/guide/type-checking):

- Daily builds: use `dts.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.

#### Output scope

`dts.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](/config/rsbuild/source.md#sourceentry), or make sure they are referenced by an existing entry.