docs: add

Author: Timeless0911

packages/core/src/types/config.ts

@@ -101,7 +101,7 @@ export type Dts =
        */
       experiments?: {
         /**
-         * [Experimental] Whether to generate declaration files with the `tsgo` compiler.
+         * [Experimental] Whether to generate declaration files with `tsgo`.
          * @defaultValue `false`
          * @see {@link https://rslib.rs/config/lib/dts#dtsexperimentstsgo}
          */

packages/plugin-dts/README.md

@@ -136,6 +136,8 @@ pluginDts({
 });
 ```
 
+> When [experiments.tsgo](#experimentstsgo) is enabled, if the project also enables [build](#build) or emits declaration files with different extensions to the same directory, `dtsExtension` may not work correctly.
+
 ### alias
 
 - **Type:** `Record<string, string>`
@@ -280,6 +282,40 @@ import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'
 
 - When set to `false`, the file extension will remain unchanged from the original import path in the rewritten import path of the output file (regardless of whether it is specified or specified as any value).
 
+### experiments
+
+- **Type:** `{ tsgo?: boolean }`
+- **Default:** `{}`
+
+Whether to enable experimental features.
+
+#### experiments.tsgo
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate declaration files with [tsgo](https://github.com/microsoft/typescript-go).
+
+To enable this option, you need to:
+
+1. Install [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) as a development dependency.
+
+```bash
+npm add @typescript/native-preview -D
+```
+
+2. Set `experiments.tsgo` to `true`.
+
+```js
+pluginDts({
+  experiments: {
+    tsgo: true,
+  },
+});
+```
+
+> `tsgo` can provide faster generation of declaration files, especially for large projects. However, since `tsgo` is still experimental, there may be unresolved issues or limitations. Therefore, please make sure to thoroughly test it in your project before enabling this option.
+
 ## Contributing
 
 Please read the [Contributing Guide](https://github.com/web-infra-dev/rslib/blob/main/CONTRIBUTING.md).

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

@@ -15,6 +15,9 @@ type Dts =
       abortOnError?: boolean;
       autoExtension?: boolean;
       alias?: Record<string, string>;
+      experiments?: {
+        tsgo?: boolean;
+      };
     }
   | boolean;
 ```
@@ -216,7 +219,9 @@ When `dts.autoExtension` is set to `true`, the declaration file extension will b
 
 ::: note
 
-It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.
+1. It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.
+
+2. When [dts.experiments.tsgo](/config/lib/dts#dtsexperimentstsgo) is enabled, if the project also enables [dts.build](/config/lib/dts#dtsbuild) or emits declaration files with different extensions to the same directory, `dts.autoExtension` may not work correctly.
 
 :::
 
@@ -245,3 +250,42 @@ export default {
   ],
 };
 ```
+
+### dts.experiments
+
+- **Type:** `{ tsgo?: boolean }`
+- **Default:** `{}`
+
+Whether to enable experimental features.
+
+#### dts.experiments.tsgo
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate declaration files with [tsgo](https://github.com/microsoft/typescript-go).
+
+To enable this option, you need to install [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) as a development dependency.
+
+<PackageManagerTabs command="add @typescript/native-preview -D" />
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      dts: {
+        // [!code highlight:3]
+        experiments: {
+          tsgo: true,
+        },
+      },
+    },
+  ],
+};
+```
+
+::: note
+
+`tsgo` can provide faster generation of declaration files, especially for large projects. However, since `tsgo` is still experimental, there may be unresolved issues or limitations. Therefore, please make sure to thoroughly test it in your project before enabling this option.
+
+:::

website/docs/en/guide/advanced/dts.mdx

@@ -40,23 +40,83 @@ Bundleless declaration files involves generating a separate declaration file for
 
 ## How to generate declaration files in Rslib
 
-Rslib defaults to generating bundleless declaration files, which using [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) and bundle declaration files is also supported by [API Extractor](https://api-extractor.com/).
-
-If you want to generate bundleless declaration files, you can:
-
-- Set `dts: true` or `dts: { bundle: false }` in the Rslib configuration file.
+Rslib supports generating declaration files using both the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) and [tsgo](https://github.com/microsoft/typescript-go), and also supports bundling declaration files with [API Extractor](https://api-extractor.com/).
+
+| Type       | Supported Method                        | Description    |
+| ---------- | --------------------------------------- | -------------- |
+| bundleless | TypeScript Compiler API                 | Default method |
+| bundleless | tsgo                                    |                |
+| bundle     | TypeScript Compiler API + API Extractor | Default method |
+| bundle     | tsgo + API Extractor                    |                |
+
+### Generate bundleless declaration files
+
+Configure in the Rslib config file:
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      dts: true; // [!code highlight]
+      // or
+      // [!code highlight:3]
+      dts: {
+        bundle: false;
+      }
+    },
+  ],
+};
+```
 
-If you want to generate bundle declaration files, you can:
+### Generate bundle declaration files
 
 1. Install `@microsoft/api-extractor` as `devDependencies`, which is the underlying tool used for bundling declaration files.
 
 import { PackageManagerTabs } from '@theme';
 
 <PackageManagerTabs command="add @microsoft/api-extractor -D" />
 
-2. Set `dts: { bundle: true }` in the Rslib configuration file.
+2. Configure in the Rslib config file:
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      // [!code highlight:3]
+      dts: {
+        bundle: true;
+      }
+    },
+  ],
+};
+```
+
+### Generate declaration files with tsgo
+
+1. Install `@typescript/native-preview` as `devDependencies`:
+
+<PackageManagerTabs command="add @typescript/native-preview -D" />
+
+2. Configure in the Rslib config file:
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      dts: {
+        // [!code highlight:3]
+        experiments: {
+          tsgo: true,
+        },
+      },
+    },
+  ],
+};
+```
+
+### Notes
 
-It should be noted that during the generation of declaration files, Rslib will automatically enforce some configuration options in `tsconfig.json` to ensure that the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) generates only declaration files.
+During the generation of declaration files, Rslib will automatically enforce some configuration options in `tsconfig.json` to ensure that the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) or [tsgo](https://github.com/microsoft/typescript-go) generates only declaration files.
 
 ```json
 {
@@ -84,6 +144,7 @@ The priority from highest to lowest of final output directory of declaration fil
 | [dts.abortOnError](/config/lib/dts#dtsabortonerror)                 | Whether to abort the build process when an error occurs during declaration files generation.                           |
 | [dts.autoExtension](/config/lib/dts#dtsautoextension)               | Whether to automatically set the declaration file extension based on the [format](/config/lib/format) option.          |
 | [dts.alias](/config/lib/dts#dtsalias)                               | The path alias of the declaration files.                                                                               |
+| [dts.experiments.tsgo](/config/lib/dts#dtsexperimentstsgo)          | Whether to generate declaration files with [tsgo](https://github.com/microsoft/TypeScript/pull/48729).                 |
 | [banner.dts](/config/lib/banner#bannerdts)                          | Inject content into the top of each declaration output file.                                                           |
 | [footer.dts](/config/lib/footer#footerdts)                          | Inject content into the bottom of each declaration file.                                                               |
 | [redirect.dts.path](/config/lib/redirect#redirectdtspath)           | Whether to automatically redirect the import paths of TypeScript declaration output files.                             |

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

@@ -15,6 +15,9 @@ type Dts =
       abortOnError?: boolean;
       autoExtension?: boolean;
       alias?: Record<string, string>;
+      experiments?: {
+        tsgo?: boolean;
+      };
     }
   | boolean;
 ```
@@ -216,7 +219,9 @@ export default {
 
 ::: note
 
-这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑，但默认值不同，因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。
+1. 这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑，但默认值不同，因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。
+
+2. 当开启 [dts.experiments.tsgo](/config/lib/dts#dtsexperimentstsgo) 时，如果项目同时开启了 [dts.build](/config/lib/dts#dtsbuild) 或者将不同后缀的类型声明文件输出到同一目录，`dts.autoExtension` 无法正常生效。
 
 :::
 
@@ -245,3 +250,42 @@ export default {
   ],
 };
 ```
+
+### dts.experiments
+
+- **类型：** `{ tsgo?: boolean }`
+- **默认值：** `{}`
+
+用于启用实验性功能。
+
+#### dts.experiments.tsgo
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否使用 [tsgo](https://github.com/microsoft/typescript-go) 生成类型声明文件。
+
+如果需要启用该选项，需要安装 [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) 作为开发依赖。
+
+<PackageManagerTabs command="add @typescript/native-preview -D" />
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      dts: {
+        // [!code highlight:3]
+        experiments: {
+          tsgo: true,
+        },
+      },
+    },
+  ],
+};
+```
+
+::: note
+
+`tsgo` 可以提供更快的类型声明文件生成速度，尤其是对于大型项目。然而，由于 `tsgo` 仍处于实验阶段，可能会存在一些未解决的问题或限制。因此，在启用该选项前，请确保在你的项目中进行充分测试。
+
+:::