docs: DTS

packages/plugin-dts/README.md

@@ -2,18 +2,169 @@
   <img alt="Rslib Banner" src="https://assets.rspack.dev/rslib/rslib-banner.png">
 </picture>
 
-# Rslib
+# rsbuild-plugin-dts
 
-Rslib is a library development tool powered by [Rsbuild](https://rsbuild.dev). It allows library developers to leverage the knowledge and ecosystem of webpack and Rspack.
+An Rsbuild plugin to emit declaration files for TypeScript which is built-in in Rslib.
 
-## Documentation
+## Using in Rslib
 
-https://lib.rsbuild.dev/
+Read [DTS](https://lib.rsbuild.dev/guide/advanced/dts) and [lib.dts](https://lib.rsbuild.dev/config/lib/dts) for more details.
+
+## Using in Rsbuild
+
+Install:
+
+```bash
+npm add rsbuild-plugin-dts -D
+```
+
+Add plugin to your `rsbuild.config.ts`:
+
+```ts
+// rsbuild.config.ts
+import { pluginDts } from 'rsbuild-plugin-dts';
+
+export default {
+  plugins: [pluginDts()],
+};
+```
+
+## Options
+
+### bundle
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to bundle the DTS files.
+
+If you want to generate [bundle DTS](https://lib.rsbuild.dev/guide/advanced/dts#bundle-dts) files, you should:
+
+- Install `@microsoft/api-extractor` as a development dependency.
+
+```bash
+npm add @microsoft/api-extractor -D
+```
+
+- Set `bundle` to `true`.
+
+```js
+pluginDts({
+  bundle: true,
+});
+```
+
+### distPath
+
+- **Type:** `string`
+
+The output directory of DTS files. The default value follows the priority below:
+
+1. The `distPath` value of the plugin options.
+2. The `declarationDir` value in the `tsconfig.json` file.
+3. The [output.distPath.root](https://rsbuild.dev/config/output/dist-path) value of Rsbuild configuration.
+
+```js
+pluginDts({
+  distPath: './dist-types',
+});
+```
+
+### build
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Determines whether to generate DTS files while building the project's references. This is equivalent to using the `--build` flag with the `tsc` command.
+
+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 DTS 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,
+});
+```
+
+### dtsExtension
+
+- **Type:** `string`
+- **Default:** `'.d.ts'`
+
+The extension of the DTS file.
+
+```js
+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 DTS 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`
+
+```js
+pluginDts({
+  autoExternal: {
+    dependencies: true,
+    optionalDependencies: true,
+    peerDependencies: true,
+    devDependencies: false,
+  },
+});
+```
+
+### banner
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the top of each DTS file.
+
+```js
+pluginDts({
+  banner: '/** @banner */',
+});
+```
+
+### footer
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+```js
+pluginDts({
+  footer: '/** @footer */',
+});
+```
+
+Inject content into the bottom of each DTS file.
 
 ## Contributing
 
 Please read the [Contributing Guide](https://github.com/web-infra-dev/rslib/blob/main/CONTRIBUTING.md).
 
 ## License
 
-Rslib is [MIT licensed](https://github.com/web-infra-dev/rslib/blob/main/LICENSE).
+[MIT licensed](https://github.com/web-infra-dev/rslib/blob/main/LICENSE).

packages/plugin-dts/src/index.ts

@@ -50,7 +50,7 @@ export const PLUGIN_DTS_NAME = 'rsbuild:dts';
 // use ts compiler API to generate bundleless dts
 // use ts compiler API and api-extractor to generate dts bundle
 // TODO: deal alias in dts
-export const pluginDts = (options: PluginDtsOptions): RsbuildPlugin => ({
+export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
   name: PLUGIN_DTS_NAME,
 
   setup(api) {

website/docs/en/config/lib/auto-external.mdx

@@ -1,3 +1,7 @@
+---
+overviewHeaders: [2, 3]
+---
+
 # lib.autoExternal
 
 - **Type:**

website/docs/en/config/lib/banner.mdx

@@ -1,3 +1,7 @@
+---
+overviewHeaders: [2, 3]
+---
+
 # lib.banner
 
 - **Type:**

website/docs/en/config/lib/dts.mdx

@@ -1,13 +1,17 @@
+---
+overviewHeaders: [2, 3]
+---
+
 # lib.dts
 
 - **Type:**
 
 ```ts
 type Dts =
   | {
-      build?: boolean;
       bundle?: boolean;
       distPath?: string;
+      build?: boolean;
       abortOnError?: boolean;
       autoExtension?: boolean;
     }
@@ -17,3 +21,166 @@ type Dts =
 - **Default:** `undefined`
 
 Configure the generation of the TypeScript declaration files.
+
+## Boolean Type
+
+DTS generation is an optional feature, you can set `dts: true` to enable [bundleless DTS](/guide/advanced/dts#bundleless-dts) generation.
+
+```ts title="rslib.config.ts" {5}
+export default {
+  lib: [
+    {
+      format: 'esm',
+      dts: true,
+    },
+  ],
+};
+```
+
+If you want to disable DTS generation, you can set `dts: false` or do not specify the `dts` option.
+
+```ts title="rslib.config.ts" {5}
+export default {
+  lib: [
+    {
+      format: 'esm',
+      dts: false,
+    },
+  ],
+};
+```
+
+## Object Type
+
+If you want to customize the DTS generation, you can set the `dts` option to an object.
+
+### dts.bundle
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to bundle the DTS files.
+
+#### Example
+
+If you want to generate [bundle DTS](/guide/advanced/dts#bundle-dts) files, you should:
+
+- Install `@microsoft/api-extractor` as a development dependency.
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add @microsoft/api-extractor -D" />
+
+- Set `dts.bundle` to `true`.
+
+```ts title="rslib.config.ts" {5-7}
+export default {
+  lib: [
+    {
+      format: 'esm',
+      dts: {
+        bundle: true,
+      },
+    },
+  ],
+};
+```
+
+::: note
+
+[@microsoft/api-extractor](https://github.com/microsoft/rushstack/tree/main/apps/api-extractor) only supports bundle DTS for single entry. If you want to generate bundle DTS for multiple entries, you can add extra lib configuration in [lib](/config/lib) field to split multiple entries into multiple lib configurations.
+
+:::
+
+### dts.distPath
+
+- **Type:** `string`
+
+The output directory of DTS 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](/config/rsbuild/output#outputdistpath) value in the current lib configuration.
+
+#### Example
+
+```ts title="rslib.config.ts" {5-7}
+export default {
+  lib: [
+    {
+      format: 'esm',
+      dts: {
+        distPath: './dist-types',
+      },
+    },
+  ],
+};
+```
+
+### dts.build
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Determines whether to generate DTS files while building the project's references. This is equivalent to using the `--build` flag with the `tsc` command.
+
+::: 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 DTS 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.
+
+```ts title="rslib.config.ts" {5-7}
+export default {
+  lib: [
+    {
+      format: 'esm',
+      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 DTS file extension based on the [format](/config/lib/format) option.
+
+#### Default Extension
+
+By default that when `dts.autoExtension` is `false`, the DTS file extension will be `.d.ts`.
+
+When `dts.autoExtension` is set to `true`, the DTS 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](/config/lib/auto-extension), but the default value is different since the DTS file extension may cause some issues with different module resolution strategies.
+
+:::

website/docs/en/config/lib/footer.mdx

@@ -1,3 +1,7 @@
+---
+overviewHeaders: [2, 3]
+---
+
 # lib.footer
 
 - **Type:**