@rsbuild/plugin-source-build 1.0.1-beta.9 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-present Bytedance, Inc. and its affiliates.
+Copyright (c) 2024 Rspack Contrib
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,243 @@
-<p align="center">
-  <a href="https://rsbuild.dev" target="blank"><img src="https://github.com/web-infra-dev/rsbuild/assets/7237365/84abc13e-b620-468f-a90b-dbf28e7e9427" alt="Rsbuild Logo" /></a>
+# @rsbuild/plugin-source-build
+
+An Rsbuild plugin to provide support for monorepo source code referencing.
+
+`@rsbuild/plugin-source-build` allows referencing source code from other subdirectories of monorepo and performs the build and hot updates.
+
+<p>
+  <a href="https://npmjs.com/package/@rsbuild/plugin-source-build">
+   <img src="https://img.shields.io/npm/v/@rsbuild/plugin-source-build?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
+  </a>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
 </p>
 
-# Rsbuild
+English | [简体中文](./README.zh-CN.md)
+
+## Usage
+
+Install:
+
+```bash
+npm add @rsbuild/plugin-source-build -D
+```
+
+Add plugin to your `rsbuild.config.ts`:
+
+```ts
+// rsbuild.config.ts
+import { pluginSourceBuild } from "@rsbuild/plugin-source-build";
+
+export default {
+  plugins: [pluginSourceBuild()],
+};
+```
+
+## Use Cases
+
+In a monorepo, there are two main ways for projects to reference each other: **artifact referencing and source code referencing**. Let's use a simple monorepo as an example to illustrate the use case of source code referencing.
+
+For example, the monorepo contains an app application and a lib:
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+The app is built using Rsbuild and relies on some methods from the lib:
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### Artifact Referencing
+
+**When using artifact referencing, the current project references the artifacts built from other sub-projects.**
+
+In the example above, the lib is written in TypeScript. Typically, we need to build the lib's code in advance to generate JavaScript artifacts so that the app can reference it correctly. When the lib's code is updated, we need to rebuild it (or use `tsc --watch`) to ensure that the app can use the latest code.
+
+The advantages of this approach are:
+
+- The build processes of each sub-project are completely independent and can have different build configurations.
+- Build caching can be applied to individual sub-projects.
+
+The disadvantages are:
+
+- The HMR chain becomes longer during local development.
+- The process becomes cumbersome when a project contains multiple lib packages.
+
+### Source Code Referencing
+
+**When using source code referencing, the current project references the source code of other sub-projects for building.**
+
+In the example mentioned earlier, when you register the `@rsbuild/plugin-source-build` and add the relevant configuration in the `lib` directory, Rsbuild will automatically reference the `src/index.ts` source code of the lib. This means that you don't need to build the lib's code in advance, and when the source code of the lib is updated, it can trigger automatic hot updates for the app.
+
+The advantages of this approach are:
+
+- The sub-project does not rely on a build tool and does not require build configurations. The code of the sub-project will be compiled by the build tool of the current project.
+- There is no need to execute the build process for the sub-projects in advance.
+- HMR is more efficient during local development.
+
+The disadvantages are:
+
+- The current project needs to support syntax features used by sub-projects and follow the same syntax specifications, such as using a consistent version of decorator syntax. If the current project and sub-projects require different build configurations, building from source code may not be suitable.
+- The current project requires compiling more code, which may result in longer build times.
+
+### Configuring Sub-projects
+
+When the `@rsbuild/plugin-source-build` is registered, the Rsbuild will prioritize reading the file specified in the `source` field of the sub-project during the build process. Therefore, you need to configure the `source` field in the package.json file of the sub-project and point it to the source code file.
+
+For example, in the following example, when the lib package is referenced, the `./src/index.ts` file will be read for building:
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+If the sub-project uses [exports](https://nodejs.org/api/packages.html#package-entry-points) field, you also need to add the `source` field in the `exports` field.
+
+```json title="package.json"
+{
+  "name": "lib",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## 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.
+
+### Introduction
+
+Project reference provides the following capabilities:
+
+- It allows TypeScript to correctly recognize the types of other sub-projects without the need to build them.
+- When you navigate the code in VS Code, it automatically takes you to the corresponding source code file of the module.
+- Rsbuild reads the project reference configuration and automatically recognizes the `tsconfig.compilerOptions.path` configuration of the sub-project, so that the use of aliases in the sub-project works correctly.
+
+### Example
+
+In the example mentioned earlier, since the app project references the lib sub-project, we need to configure the `references` options in the app project's `tsconfig.json` to point to the relative directory of the lib:
+
+```json title="app/tsconfig.json"
+{
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+At the same time, we need to set `composite` to `true` in the lib project's `tsconfig.json`:
+
+```json title="lib/A/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+}
+```
+
+After adding these two options, the project reference is already configured. You can restart VS Code to see the effects of the configuration.
+
+Note that the above example is a simplified one. In real monorepo projects, there may be more complex dependency relationships. You need to add a complete `references` configuration for the functionality to work correctly.
+
+> If you want to learn more about project reference, please refer to the official documentation on [TypeScript - Project References](https://typescriptlang.org/docs/handbook/project-references).
+
+## Options
+
+### sourceField
+
+- **Type:** `string`
+- **Default:** `'source'`
+
+Used to configure the resolve field of the source code files.
+
+For example, when configured as `my-source`:
+
+```ts
+pluginSourceBuild({
+  sourceField: "my-source",
+});
+```
+
+In `package.json`, the source code file path can be specified using `my-source`:
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "my-source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "my-source": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}
+```
+
+### resolvePriority
+
+- **Type:** `'source' | 'output'`
+- **Default:** `'source'`
+
+Used to control the priority of reading the source code or the output code.
+
+By default, `@rsbuild/plugin-source-build` will reading the source code first, for example, in the following example, it will read the `source` field.
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+When `resolvePriority` is set to `'output'`, `@rsbuild/plugin-source-build` will read the output code first, i.e., the code from the `main` or `module` field.
+
+```ts
+pluginSourceBuild({
+  resolvePriority: "output",
+});
+```
 
-The Rspack-based build tool. It's fast, out-of-the-box and extensible.
+- The `exports` field in package.json is not affected by `resolvePriority`.
+- The keys order in `exports` determines the resolving order, earlier declared keys having higher priority.
 
-## Documentation
+## Caveat
 
-https://rsbuild.dev/
+When using `@rsbuild/plugin-source-build`, there are a few things to keep in mind:
 
-## Contributing
+1. Ensure that the current project can compile the syntax or features used in the sub-project. For example, if the sub-project uses Stylus to write CSS, the current app needs to support Stylus compilation.
+2. Ensure that the current project has the same code syntax and features as the sub-project, such as consistent syntax versions for decorators.
+3. Source code building may have some limitations. When encountering issues, you can remove the `source` field from the sub-project's package.json and debug using the built artifacts of the sub-project.
+4. When `composite: true` is enabled, TypeScript will generate `*.tsbuildinfo` temporary files. You need to add these temporary files to the `.gitignore` file.
 
-Please read the [Contributing Guide](https://github.com/web-infra-dev/rsbuild/blob/main/CONTRIBUTING.md).
+```text title=".gitignore"
+*.tsbuildinfo
+```
 
 ## License
 
-Rsbuild is [MIT licensed](https://github.com/web-infra-dev/rsbuild/blob/main/LICENSE).
+[MIT](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,241 @@
+# @rsbuild/plugin-source-build
+
+提供对 monorepo 源代码引用的支持。
+
+`@rsbuild/plugin-source-build` 用于 monorepo 开发场景，它支持从当前项目引用其他子目录的源代码，并完成构建和热更新。
+
+<p>
+  <a href="https://npmjs.com/package/@rsbuild/plugin-source-build">
+   <img src="https://img.shields.io/npm/v/@rsbuild/plugin-source-build?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
+  </a>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
+</p>
+
+## 使用
+
+安装：
+
+```bash
+npm add @rsbuild/plugin-source-build -D
+```
+
+在 `rsbuild.config.ts` 里注册插件:
+
+```ts
+// rsbuild.config.ts
+import { pluginSourceBuild } from "@rsbuild/plugin-source-build";
+
+export default {
+  plugins: [pluginSourceBuild()],
+};
+```
+
+## 使用场景
+
+在 monorepo 中，子项目互相引用主要有两种方式 —— **产物引用和源码引用**。我们以一个最简单的 monorepo 为例子，来介绍源码引用的使用场景。
+
+比如 monorepo 中包含了一个 app 应用和一个 lib 包：
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+其中，app 是基于 Rsbuild 构建的，app 依赖了 lib 中的一些方法：
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### 产物引用
+
+**产物引用指的是当前项目引用其他子项目构建后的产物。**
+
+比如上述例子中的 lib 是使用 TypeScript 编写的，通常情况下，我们需要提前构建 lib 的代码，生成 JavaScript 产物，这样 app 才可以正确引用它。当 lib 代码更新时，还需要重新执行一次构建（或者使用 `tsc --watch`），否则 app 无法引用到最新的代码。
+
+这种方式的优势在于：
+
+- 各个子项目的构建过程是完全独立的，可以拥有不同的构建配置。
+- 可以针对子项目进行构建缓存。
+
+劣势在于：
+
+- 本地开发时 HMR 的链路变长。
+- 当一个项目中包含多个 lib 包时，以上过程会显得十分繁琐。
+
+### 源码引用
+
+**源码引用指的是当前项目引用其他子项目的源码进行构建。**
+
+比如上述例子，当你注册了 `@rsbuild/plugin-source-build`，并在 lib 中添加相关配置后，Rsbuild 会自动引用 lib 的 `src/index.ts` 源代码。这意味着，你不需要提前构建 lib 的代码，并且当 lib 的源代码更新时，也可以自动触发 app 的热更新。
+
+这种方式的优势在于：
+
+- 子项目不依赖构建工具，也不需要添加构建配置，子项目的代码会被当前项目的构建工具编译。
+- 不需要提前执行子项目的构建流程。
+- 本地开发时 HMR 更高效。
+
+劣势在于：
+
+- 当前项目需要支持子项目用到的语法特性，并且遵循相同的语法规范，比如使用一致的装饰器语法版本。如果当前项目和子项目需要使用不同的编译配置，则不适合使用 `@rsbuild/plugin-source-build`。
+- 当前项目需要编译更多的代码，因此构建时间可能会变长。
+
+### 配置子项目
+
+当注册 `@rsbuild/plugin-source-build`后，Rsbuild 在构建过程中，会优先读取子项目的 `source` 字段对应的文件。因此，你需要在子项目的 package.json 中配置 `source` 字段，并且指向源码文件路径。
+
+比如以下例子，当 lib 包被引用时，会读取 `./src/index.ts` 文件进行构建：
+
+```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",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## 配置 Project Reference
+
+在 TypeScript 项目中，你需要使用 TypeScript 提供的 [Project Reference](https://typescriptlang.org/docs/handbook/project-references) 能力，它可以帮助你更好地使用源码开发。
+
+### 介绍
+
+Project reference 提供了以下能力：
+
+- 使 TypeScript 可以正确识别其他子项目的类型，而无须对子项目进行构建。
+- 当你在 VS Code 内进行代码跳转时，VS Code 可以自动跳转到对应模块的源代码文件。
+- Rsbuild 会读取 project reference 配置，并自动识别子项目的 `tsconfig.compilerOptions.path` 配置，从而让子项目的别名可以正确生效。
+
+### 示例
+
+在上文的例子中，由于 app 引用了 lib 子项目，我们需要在 app 的 `tsconfig.json` 内配置 `references`，并指向 lib 对应的相对目录：
+
+```json title="app/tsconfig.json"
+{
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+同时，需要在 lib 子项目的 `tsconfig.json` 内配置 `composite` 为 `true`：
+
+```json title="lib/A/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+}
+```
+
+添加以上两个选项后，project reference 就已经配置完成了，你可以重新启动 VS Code 来查看配置以后的效果。
+
+注意以上只是一个最简单的例子，在实际的 monorepo 项目中，可能会有更复杂的依赖关系，你需要添加完整的 `references` 配置，才能使上述功能正确运作。
+
+> 如果你想了解更多关于 project reference 的内容，请阅读 [TypeScript - Project References](https://typescriptlang.org/docs/handbook/project-references) 官方文档。
+
+## 选项
+
+### sourceField
+
+- **类型：** `string`
+- **默认值：** `'source'`
+
+用于配置源代码文件对应的解析字段。
+
+比如配置为 `my-source`：
+
+```ts
+pluginSourceBuild({
+  sourceField: "my-source",
+});
+```
+
+在 `package.json` 中，即可通过 `my-source` 指定源代码文件的路径：
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "my-source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "my-source": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}
+```
+
+### resolvePriority
+
+- **类型：** `'source' | 'output'`
+- **默认值：** `'source'`
+
+用于控制优先读取源代码还是产物代码。
+
+默认情况下，`@rsbuild/plugin-source-build`会优先读取源代码，比如在下面的例子中，它会读取 `source` 字段。
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+当 `resolvePriority` 设置为 `'output'` 时，`@rsbuild/plugin-source-build`会优先读取产物代码，即 `main` 或 `module` 字段指向的代码。
+
+```ts
+pluginSourceBuild({
+  resolvePriority: "output",
+});
+```
+
+- package.json 中的 `exports` 字段不受 `resolvePriority` 的影响。
+- `exports` 中 key 的声明顺序决定了读取顺序，较早声明的 key 具有更高的优先级。
+
+## 注意事项
+
+在使用 `@rsbuild/plugin-source-build`的时候，需要注意几点：
+
+1. 需要保证当前项目可以编译子项目里使用的语法或特性。比如子项目使用了 Stylus 来编写 CSS 样式，那就需要当前 app 支持 Stylus 编译。
+2. 需要保证当前项目与子项目使用的代码语法特性相同，例如装饰器的语法版本一致。
+3. 源码构建可能存在一些限制。如果在使用中遇到问题，你可以将子项目 package.json 中的 `source` 字段移除，使用子项目的构建产物进行调试。
+4. 开启 `composite: true` 后，TypeScript 会生成 `*.tsbuildinfo` 临时文件，你需要将这些临时文件加入 .gitignore 中。
+
+```text title=".gitignore"
+*.tsbuildinfo
+```
+
+## License
+
+[MIT](./LICENSE).

package/{dist-types → dist}/common/getBaseData.d.ts

@@ -1,5 +1,5 @@
-import type { MonorepoAnalyzer } from '../types';
-import type { GetProjectsFunc } from './getProjects';
+import type { MonorepoAnalyzer } from '../types/index.js';
+import type { GetProjectsFunc } from './getProjects.js';
 export interface IMonorepoBaseData {
     isMonorepo: boolean;
     type: string;

package/{dist-types → dist}/common/getProjects.d.ts

@@ -1,4 +1,4 @@
-import type { Project } from '../project';
-import type { IMonorepoBaseData } from './getBaseData';
+import type { Project } from '../project.js';
+import type { IMonorepoBaseData } from './getBaseData.js';
 export type GetProjectsFunc = (rootPath: string) => Promise<Project[]> | Project[];
 export declare const getMonorepoSubProjects: (monorepoBaseData: IMonorepoBaseData) => Promise<Project[]>;

package/dist/common/index.d.ts

@@ -0,0 +1,6 @@
+export * from './getBaseData.js';
+export * from './isMonorepo.js';
+export { getMonorepoSubProjects } from './getProjects.js';
+export { getProjects as getPnpmMonorepoSubProjects } from './pnpm.js';
+export { getProjects as getRushMonorepoSubProjects } from './rush.js';
+export type { GetProjectsFunc } from './getProjects.js';

package/{dist-types → dist}/common/pnpm.d.ts

@@ -1,2 +1,2 @@
-import { Project } from '../project';
+import { Project } from '../project.js';
 export declare const getProjects: (monorepoRoot: string) => Promise<Project[]>;

package/{dist-types → dist}/common/rush.d.ts

@@ -1,2 +1,2 @@
-import { Project } from '../project';
+import { Project } from '../project.js';
 export declare const getProjects: (monorepoRoot: string) => Promise<Project[]>;