docs: add source code build documentation (#4210)

* docs(builder-doc): add source-code build documentation

* docs(main-doc): add source code build documentation

* Update packages/document/builder-doc/docs/zh/config/experiments/sourceBuild.md

* Update packages/document/builder-doc/docs/en/config/experiments/sourceBuild.md

---------

Co-authored-by: neverland <[email protected]>

.changeset/neat-readers-walk.md

@@ -0,0 +1,7 @@
+---
+'@modern-js/builder-doc': patch
+'@modern-js/main-doc': patch
+---
+
+docs: add source code build documentation
+docs: 添加源码构建文档

packages/document/builder-doc/docs/en/api/config-experiments.mdx

@@ -13,3 +13,10 @@ If you meet issues with experimental features, please disable the config first a
 import LazyCompilation from '@en/config/experiments/lazyCompilation.md';
 
 <LazyCompilation />
+
+## experiments.sourceBuild
+
+import SourceBuild from '@en/config/experiments/sourceBuild.md';
+
+<SourceBuild />
+

packages/document/builder-doc/docs/en/config/experiments/sourceBuild.md

@@ -0,0 +1,15 @@
+- **Type:** `boolean`
+- **Default:** `false`
+- **Bundler:** `only support webpack`
+
+Used to enable the ability for source code building. When this configuration option is enabled, Builder will read the source code files corresponding to the `source` field in the sub-project's package.json and compile them.
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+More detail can see ["Advanced - Source-code Build Mode"](en/guide/advanced/source-build.md)。

packages/document/builder-doc/docs/en/guide/advanced/source-build.md

@@ -0,0 +1,56 @@
+# Source-code Build Mode
+
+The source-code build mode allows developers to use dependent subproject source code in Monorepo. This allows HMR (Hot Module Replacement) to be performed without starting a subproject build task.
+
+## Enable source-code build
+
+You can enable this feature by setting [`experiments.sourceBuild`](/api/config-experiments.html#experimentssourcebuild) to `true`.
+
+```ts
+export default {
+    experiments: {
+        sourceBuild: true,
+    },
+};
+```
+
+## Specify the sub-projects that need to read the source code
+
+When you need to read the source code of a subproject, you need to make sure that the package.json of the subproject contains a `source` field, and that the path to the file corresponding to that field is the path to the source code file.
+
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+If the [`exports`](https://nodejs.org/api/packages.html#package-entry-points) configuration exists for the subproject, then you need to add the `source` field to exports at the same time.
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## Caveat
+
+There are a few things to keep in mind when using the source-code build mode:
+
+1. Ensure that all configurations or features used by sub-projects need to be set in the Builder's configuration file.
+2. Ensure that the current project uses the same code syntax as the subprojects, such as the syntax of the decorators.
+3. There may be some limitations in the source build. When you encounter problems, you can remove the `source` field in the package.json of the subproject and use the build product of the subproject for debugging.

packages/document/builder-doc/docs/zh/api/config-experiments.mdx

@@ -13,3 +13,9 @@ extractApiHeaders: [2]
 import LazyCompilation from '@zh/config/experiments/lazyCompilation.md';
 
 <LazyCompilation />
+
+## experiments.sourceBuild
+
+import SourceBuild from '@zh/config/experiments/sourceBuild.md';
+
+<SourceBuild />

packages/document/builder-doc/docs/zh/config/experiments/sourceBuild.md

@@ -0,0 +1,15 @@
+- **类型：** `boolean`
+- **默认值：** `false`
+- **打包工具：** `仅支持 webpack`
+
+用于开启源码构建的能力。当开启此配置项时，Builder 会读取子项目 package.json 的 `source` 字段对应的源码文件，并进行编译。
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+更多信息可参考[「进阶-源码构建模式」](/guide/advanced/source-build.md)。

packages/document/builder-doc/docs/zh/guide/advanced/source-build.md

@@ -0,0 +1,48 @@
+# 源码构建模式
+
+源码构建模式允许开发者在 Monorepo 场景下使用依赖的子项目源码进行开发。这样可以在不启动子项目构建任务的情况下进行 HMR (Hot Module Replacement)。
+
+## 开启特性
+
+你可以通过设置 [`experiments.sourceBuild`](/api/config-experiments.html#experimentssourcebuild) 为 `true` 来开启该功能。
+
+## 指定需要读取源码的子项目
+
+当需要读取某一个子项目源码的时候，需要确保子项目的 package.json 中包含 `source` 字段，并且该字段对应的文件路径为源码文件路径。
+
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+如果子项目存在 [`exports`](https://nodejs.org/api/packages.html#package-entry-points) 配置的时候，那么需要同时在 exports 中增加 `source` 字段。
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## 注意事项
+
+在使用源码构建模式的时候，需要注意几点：
+
+1. 保证所有子项目使用的配置或者特性都需要在 Builder 的配置文件里设置。
+2. 保证当前项目与子项目使用的代码语法特性相同，例如装饰器的语法。
+3. 源码构建可能存在一定的限制。当遇到问题的时候，可以将子项目 package.json 中的 `source` 字段移除，使用子项目的构建产物进行调试。

packages/document/builder-doc/modern.config.ts

@@ -76,6 +76,7 @@ function getSidebar(lang: 'zh' | 'en'): Sidebar {
           getLink('/guide/advanced/browserslist'),
           getLink('/guide/advanced/browser-compatibility'),
           getLink('/guide/advanced/custom-webpack-config'),
+          getLink('/guide/advanced/source-build'),
         ],
       },
       {

packages/document/main-doc/docs/en/configure/app/experiments/source-build.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: sourceBuild
+---
+
+# experiments.sourceBuild
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [experiments.sourceBuild](https://modernjs.dev/builder/en/api/config-experiments.html#experimentssourcebuild).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/experiments/sourceBuild.md';
+
+<Main />

packages/document/main-doc/docs/zh/configure/app/experiments/source-build.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: sourceBuild
+---
+
+# experiments.sourceBuild
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [experiments.sourceBuild](https://modernjs.dev/builder/api/config-experiments.html#experimentssourcebuild)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/experiments/sourceBuild.md';
+
+<Main />

packages/document/main-doc/scripts/summary.en.json

@@ -1 +1 @@
-[{"name":"assetPrefix","dirname":"dev"},{"name":"beforeStartUrl","dirname":"dev"},{"name":"hmr","dirname":"dev"},{"name":"host","dirname":"dev"},{"name":"https","dirname":"dev"},{"name":"port","dirname":"dev"},{"name":"progressBar","dirname":"dev"},{"name":"startUrl","dirname":"dev"},{"name":"lazyCompilation","dirname":"experiments"},{"name":"appIcon","dirname":"html"},{"name":"crossorigin","dirname":"html"},{"name":"disableHtmlFolder","dirname":"html"},{"name":"favicon","dirname":"html"},{"name":"faviconByEntries","dirname":"html"},{"name":"inject","dirname":"html"},{"name":"injectByEntries","dirname":"html"},{"name":"meta","dirname":"html"},{"name":"metaByEntries","dirname":"html"},{"name":"mountId","dirname":"html"},{"name":"scriptLoading","dirname":"html"},{"name":"tags","dirname":"html"},{"name":"tagsByEntries","dirname":"html"},{"name":"template","dirname":"html"},{"name":"templateByEntries","dirname":"html"},{"name":"templateParameters","dirname":"html"},{"name":"templateParametersByEntries","dirname":"html"},{"name":"title","dirname":"html"},{"name":"titleByEntries","dirname":"html"},{"name":"assetPrefix","dirname":"output"},{"name":"assetsRetry","dirname":"output"},{"name":"charset","dirname":"output"},{"name":"cleanDistPath","dirname":"output"},{"name":"convertToRem","dirname":"output"},{"name":"copy","dirname":"output"},{"name":"cssModuleLocalIdentName","dirname":"output"},{"name":"cssModules","dirname":"output"},{"name":"dataUriLimit","dirname":"output"},{"name":"disableCssExtract","dirname":"output"},{"name":"disableCssModuleExtension","dirname":"output"},{"name":"disableFilenameHash","dirname":"output"},{"name":"disableInlineRuntimeChunk","dirname":"output"},{"name":"disableMinimize","dirname":"output"},{"name":"disableSourceMap","dirname":"output"},{"name":"disableSvgr","dirname":"output"},{"name":"disableTsChecker","dirname":"output"},{"name":"distPath","dirname":"output"},{"name":"enableAssetFallback","dirname":"output"},{"name":"enableAssetManifest","dirname":"output"},{"name":"enableCssModuleTSDeclaration","dirname":"output"},{"name":"enableInlineScripts","dirname":"output"},{"name":"enableInlineStyles","dirname":"output"},{"name":"enableLatestDecorators","dirname":"output"},{"name":"externals","dirname":"output"},{"name":"filename","dirname":"output"},{"name":"legalComments","dirname":"output"},{"name":"overrideBrowserslist","dirname":"output"},{"name":"polyfill","dirname":"output"},{"name":"svgDefaultExport","dirname":"output"},{"name":"buildCache","dirname":"performance"},{"name":"bundleAnalyze","dirname":"performance"},{"name":"chunkSplit","dirname":"performance"},{"name":"printFileSize","dirname":"performance"},{"name":"profile","dirname":"performance"},{"name":"removeConsole","dirname":"performance"},{"name":"removeMomentLocale","dirname":"performance"},{"name":"checkSyntax","dirname":"security"},{"name":"nonce","dirname":"security"},{"name":"sri","dirname":"security"},{"name":"alias","dirname":"source"},{"name":"compileJsDataURI","dirname":"source"},{"name":"define","dirname":"source"},{"name":"exclude","dirname":"source"},{"name":"globalVars","dirname":"source"},{"name":"include","dirname":"source"},{"name":"moduleScopes","dirname":"source"},{"name":"preEntry","dirname":"source"},{"name":"resolveExtensionPrefix","dirname":"source"},{"name":"resolveMainFields","dirname":"source"},{"name":"transformImport","dirname":"source"},{"name":"autoprefixer","dirname":"tools"},{"name":"babel","dirname":"tools"},{"name":"cssExtract","dirname":"tools"},{"name":"cssLoader","dirname":"tools"},{"name":"devServer","dirname":"tools"},{"name":"htmlPlugin","dirname":"tools"},{"name":"inspector","dirname":"tools"},{"name":"less","dirname":"tools"},{"name":"minifyCss","dirname":"tools"},{"name":"postcss","dirname":"tools"},{"name":"pug","dirname":"tools"},{"name":"rspack","dirname":"tools"},{"name":"sass","dirname":"tools"},{"name":"styleLoader","dirname":"tools"},{"name":"styledComponents","dirname":"tools"},{"name":"terser","dirname":"tools"},{"name":"tsChecker","dirname":"tools"},{"name":"tsLoader","dirname":"tools"},{"name":"webpack","dirname":"tools"},{"name":"webpackChain","dirname":"tools"}]
+[{"name":"assetPrefix","dirname":"dev"},{"name":"beforeStartUrl","dirname":"dev"},{"name":"hmr","dirname":"dev"},{"name":"host","dirname":"dev"},{"name":"https","dirname":"dev"},{"name":"port","dirname":"dev"},{"name":"progressBar","dirname":"dev"},{"name":"startUrl","dirname":"dev"},{"name":"lazyCompilation","dirname":"experiments"},{"name":"sourceBuild","dirname":"experiments"},{"name":"appIcon","dirname":"html"},{"name":"crossorigin","dirname":"html"},{"name":"disableHtmlFolder","dirname":"html"},{"name":"favicon","dirname":"html"},{"name":"faviconByEntries","dirname":"html"},{"name":"inject","dirname":"html"},{"name":"injectByEntries","dirname":"html"},{"name":"meta","dirname":"html"},{"name":"metaByEntries","dirname":"html"},{"name":"mountId","dirname":"html"},{"name":"scriptLoading","dirname":"html"},{"name":"tags","dirname":"html"},{"name":"tagsByEntries","dirname":"html"},{"name":"template","dirname":"html"},{"name":"templateByEntries","dirname":"html"},{"name":"templateParameters","dirname":"html"},{"name":"templateParametersByEntries","dirname":"html"},{"name":"title","dirname":"html"},{"name":"titleByEntries","dirname":"html"},{"name":"assetPrefix","dirname":"output"},{"name":"assetsRetry","dirname":"output"},{"name":"charset","dirname":"output"},{"name":"cleanDistPath","dirname":"output"},{"name":"convertToRem","dirname":"output"},{"name":"copy","dirname":"output"},{"name":"cssModuleLocalIdentName","dirname":"output"},{"name":"cssModules","dirname":"output"},{"name":"dataUriLimit","dirname":"output"},{"name":"disableCssExtract","dirname":"output"},{"name":"disableCssModuleExtension","dirname":"output"},{"name":"disableFilenameHash","dirname":"output"},{"name":"disableInlineRuntimeChunk","dirname":"output"},{"name":"disableMinimize","dirname":"output"},{"name":"disableSourceMap","dirname":"output"},{"name":"disableSvgr","dirname":"output"},{"name":"disableTsChecker","dirname":"output"},{"name":"distPath","dirname":"output"},{"name":"enableAssetFallback","dirname":"output"},{"name":"enableAssetManifest","dirname":"output"},{"name":"enableCssModuleTSDeclaration","dirname":"output"},{"name":"enableInlineScripts","dirname":"output"},{"name":"enableInlineStyles","dirname":"output"},{"name":"enableLatestDecorators","dirname":"output"},{"name":"externals","dirname":"output"},{"name":"filename","dirname":"output"},{"name":"legalComments","dirname":"output"},{"name":"overrideBrowserslist","dirname":"output"},{"name":"polyfill","dirname":"output"},{"name":"svgDefaultExport","dirname":"output"},{"name":"buildCache","dirname":"performance"},{"name":"bundleAnalyze","dirname":"performance"},{"name":"chunkSplit","dirname":"performance"},{"name":"printFileSize","dirname":"performance"},{"name":"profile","dirname":"performance"},{"name":"removeConsole","dirname":"performance"},{"name":"removeMomentLocale","dirname":"performance"},{"name":"checkSyntax","dirname":"security"},{"name":"nonce","dirname":"security"},{"name":"sri","dirname":"security"},{"name":"alias","dirname":"source"},{"name":"compileJsDataURI","dirname":"source"},{"name":"define","dirname":"source"},{"name":"exclude","dirname":"source"},{"name":"globalVars","dirname":"source"},{"name":"include","dirname":"source"},{"name":"moduleScopes","dirname":"source"},{"name":"preEntry","dirname":"source"},{"name":"resolveExtensionPrefix","dirname":"source"},{"name":"resolveMainFields","dirname":"source"},{"name":"transformImport","dirname":"source"},{"name":"autoprefixer","dirname":"tools"},{"name":"babel","dirname":"tools"},{"name":"cssExtract","dirname":"tools"},{"name":"cssLoader","dirname":"tools"},{"name":"devServer","dirname":"tools"},{"name":"htmlPlugin","dirname":"tools"},{"name":"inspector","dirname":"tools"},{"name":"less","dirname":"tools"},{"name":"minifyCss","dirname":"tools"},{"name":"postcss","dirname":"tools"},{"name":"pug","dirname":"tools"},{"name":"rspack","dirname":"tools"},{"name":"sass","dirname":"tools"},{"name":"styleLoader","dirname":"tools"},{"name":"styledComponents","dirname":"tools"},{"name":"terser","dirname":"tools"},{"name":"tsChecker","dirname":"tools"},{"name":"tsLoader","dirname":"tools"},{"name":"webpack","dirname":"tools"},{"name":"webpackChain","dirname":"tools"}]