From defa790204eb35ed007ccbf34eeaf9613b993920 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 10 Oct 2025 10:43:51 +0800
Subject: [PATCH] docs: update README to recommend custom source field

---
 README.md       | 24 ++++++++++++++++++------
 README.zh-CN.md | 24 ++++++++++++++++++------
 2 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 80d1640..07a094f 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,18 @@ If the sub-project uses [exports](https://nodejs.org/api/packages.html#package-e
 }
 ```
 
+### Customizing Source Field
+
+Although the plugin uses the `source` field by default to specify the source file, we recommend configuring a custom field through the [sourceField](#sourceField) option (for example, `@custom/source`, where `custom` can be replaced with any scope name).
+
+```ts
+pluginSourceBuild({
+  sourceField: "@custom/source",
+});
+```
+
+This is because some packages (such as Mobx) also define a `source` field in their `package.json`. If not distinguished, Rsbuild may mistakenly resolve the source files of those dependencies, leading to unexpected build results or type issues. By using a custom field, you can avoid such conflicts and ensure that Rsbuild behaves predictably when resolving dependencies.
+
 ## Configure Project Reference
 
 In a TypeScript project, you need to use the capability provided by TypeScript called [Project Reference](https://typescriptlang.org/docs/handbook/project-references). It helps you develop source code more effectively.
@@ -154,7 +166,7 @@ At the same time, we need to set `composite` to `true` in the lib project's `tsc
 {
   "compilerOptions": {
     "composite": true
-  },
+  }
 }
 ```
 
@@ -173,24 +185,24 @@ Note that the above example is a simplified one. In real monorepo projects, ther
 
 Used to configure the resolve field of the source code files.
 
-For example, when configured as `my-source`:
+For example, when configured as `@custom/source`:
 
 ```ts
 pluginSourceBuild({
-  sourceField: "my-source",
+  sourceField: "@custom/source",
 });
 ```
 
-In `package.json`, the source code file path can be specified using `my-source`:
+In `package.json`, the source code file path can be specified using `@custom/source`:
 
 ```json title="package.json"
 {
   "name": "lib",
   "main": "./dist/index.js",
-  "my-source": "./src/index.ts",
+  "@custom/source": "./src/index.ts",
   "exports": {
     ".": {
-      "my-source": "./src/index.ts",
+      "@custom/source": "./src/index.ts",
       "default": "./dist/index.js"
     }
   }
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 89c2c24..8f3c561 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -120,6 +120,18 @@ monorepo
 }
 ```
 
+### 自定义 source 字段
+
+虽然插件默认使用 `source` 字段来指定源代码文件，但我们更推荐通过 [sourceField](#sourceField) 选项配置一个自定义字段（例如 `@custom/source`，其中 `custom` 可以替换为任意 scope 名称）。
+
+```ts
+pluginSourceBuild({
+  sourceField: "@custom/source",
+});
+```
+
+这是因为某些三方库（例如 Mobx）的 `package.json` 中也包含 `source` 字段，如果不进行区分，Rsbuild 可能会错误地解析这些库的源文件路径，从而导致意料之外的构建结果或类型问题。使用自定义字段可以避免此类冲突，确保 Rsbuild 在解析依赖关系时保持可控的行为。
+
 ## 配置 Project Reference
 
 在 TypeScript 项目中，你需要使用 TypeScript 提供的 [Project Reference](https://typescriptlang.org/docs/handbook/project-references) 能力，它可以帮助你更好地使用源码开发。
@@ -152,7 +164,7 @@ Project reference 提供了以下能力：
 {
   "compilerOptions": {
     "composite": true
-  },
+  }
 }
 ```
 
@@ -171,24 +183,24 @@ Project reference 提供了以下能力：
 
 用于配置源代码文件对应的解析字段。
 
-比如配置为 `my-source`：
+比如配置为 `@custom/source`：
 
 ```ts
 pluginSourceBuild({
-  sourceField: "my-source",
+  sourceField: "@custom/source",
 });
 ```
 
-在 `package.json` 中，即可通过 `my-source` 指定源代码文件的路径：
+在 `package.json` 中，即可通过 `@custom/source` 指定源代码文件的路径：
 
 ```json title="package.json"
 {
   "name": "lib",
   "main": "./dist/index.js",
-  "my-source": "./src/index.ts",
+  "@custom/source": "./src/index.ts",
   "exports": {
     ".": {
-      "my-source": "./src/index.ts",
+      "@custom/source": "./src/index.ts",
       "default": "./dist/index.js"
     }
   }