docs: add FAQ for declaration files directory structure

Timeless0911 · Timeless0911 · commit 8dafd3c8eaf3 · 2026-01-21T12:47:18.000+08:00
diff --git a/website/docs/en/guide/faq/features.mdx b/website/docs/en/guide/faq/features.mdx
@@ -216,6 +216,32 @@ export default {
 
 In addition, if you only want to specify a few dependencies to be bundled into the declaration output files, you can configure [dts.bundle.bundledPackages](/config/lib/dts#dtsbundlebundledpackages) to achieve this. All other dependencies not in this configuration will be excluded.
 
+### Why does the directory structure of the declaration files not meet expectations?
+
+The directory structure of the declaration files is related to the `rootDir` configuration in `tsconfig.json`. If `rootDir` is not configured explicitly, TypeScript will automatically infer it, which may cause the output structure to be inconsistent with your expectations.
+
+For example, assuming your project structure is as follows, when `composite` is set to `true`, TypeScript will automatically infer `rootDir` as the project root directory, and the declaration files will be output to `dist/src/index.d.ts`.
+
+```
+.
+├── dist
+│   └── src
+│       └── index.d.ts
+├── src
+│   └── index.ts
+└── tsconfig.json
+```
+
+You can explicitly set `rootDir` to `'./src'` in `tsconfig.json` to ensure that declaration files are output to the expected `dist/index.d.ts`.
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "rootDir": "./src"
+  }
+}
+```
+
 ## Rsbuild plugin
 
 ### Why does using `modifyRsbuildConfig` to modify the configuration does not take effect?
diff --git a/website/docs/zh/guide/faq/features.mdx b/website/docs/zh/guide/faq/features.mdx
@@ -216,6 +216,32 @@ export default {
 
 此外，如果只想指定某几个依赖项打包进类型声明文件产物中，可以通过配置 [dts.bundle.bundledPackages](/config/lib/dts#dtsbundlebundledpackages) 来实现，不在该配置中的所有其他依赖项都会被排除。
 
+### 为什么类型声明文件的目录结构不符合预期？
+
+类型声明文件的目录结构与 `tsconfig.json` 中的 `rootDir` 配置有关，如果未显式配置 `rootDir`，TypeScript 会进行自动推断，这可能导致输出结构与你的预期不符。
+
+例如，假设你的项目结构如下，当 `composite` 设置为 `true` 时，TypeScript 会将 `rootDir` 自动推断为项目根目录，此时类型声明文件会输出到 `dist/src/index.d.ts`。
+
+```
+.
+├── dist
+│   └── src
+│       └── index.d.ts
+├── src
+│   └── index.ts
+└── tsconfig.json
+```
+
+你可以在 `tsconfig.json` 中显式设置 `rootDir` 为 `'./src'`，以确保类型声明文件输出到预期的 `dist/index.d.ts`。
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "rootDir": "./src"
+  }
+}
+```
+
 ## Rsbuild 插件
 
 ### 为什么使用 `modifyRsbuildConfig` 修改配置不生效？
