rsbuild-plugin-workspace-dev 0.0.1-beta.1 → 0.0.1

package/README.md

@@ -11,12 +11,14 @@ Start monorepo sub-projects in topological order.
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
 </p>
 
+English | [简体中文](./README.zh-CN.md)
+
 ## Usage
 
 Install:
 
 ```bash
-npm add rsbuild-plugin-workspace-dev -D
+pnpm add rsbuild-plugin-workspace-dev -D
 ```
 
 Register the plugin in `rsbuild.config.ts`:
@@ -56,7 +58,7 @@ Here, app is built with Rsbuild, and lib is built with Rslib. The app depends on
 }
 ```
 
-`lib2` depends on `lib3`:
+lib2 depends on lib3:
 
 ```json
 {
@@ -81,12 +83,17 @@ Whether a sub-project has finished starting is determined by matching sub-projec
 
 ## Options
 
-### projectConfig
+### projects
 Configure how sub-projects are started and define custom log matching logic.
 
 - Type:
 ```
-interface ProjectConfig {
+type projects = {
+  // The key is the name of the sub-project's package.json file.
+  [key: string]: Projects;
+}
+
+interface projects {
   /**
    * Custom sub-project start command. Default is `dev` (runs `npm run dev`).
    */
@@ -102,14 +109,25 @@ interface ProjectConfig {
    */
   skip?: boolean;
 }
+
+
+// For example, to configure lib1 sub-project to use build:watch command and match watch success log
+pluginWorkspaceDev({
+  projects: {
+    lib1: {
+      command: 'build:watch',
+      match: (stdout) => stdout.includes('watch success'),
+    },
+  },
+})
 ```
 
-### ignoreSelf
+### startCurrent
 
 - Type: `boolean`
-- Default: `true`
+- Default: `false`
 
-Whether to ignore starting the current project. The default is `true`. In most cases, you start the current project manually, so the plugin does not interfere.
+Whether to also start the current project. The default is `false`. In most cases, you start the current project manually, so the plugin does not interfere.
 
 Consider a scenario where docs and lib are in the same project, and docs needs to debug the output of lib. In this case, you want to run `pnpm doc` for the docs, while lib should run `pnpm dev`. After configuring this option in your Rspress config, starting `pnpm doc` will automatically run `pnpm dev` to start the lib sub-project.
 
@@ -144,6 +162,36 @@ Set the current working directory. The default is the current project directory;
 
 Set the directory where the workspace file resides. The default is the current project directory; usually no configuration is needed.
 
+## Frequently Asked Questions
+
+### Project startup stuck
+Stuck may be due to slow sub-project builds, etc. The lack of log output is because, by default, sub-project logs are output all at once after startup (to avoid interleaving sub-project logs). You can enable debug mode by adding an environment variable, which will allow sub-project logs to be output in real time.
+
+```
+DEBUG=rsbuild pnpm dev
+```
+
+### Some projects don't need to start
+
+If some sub-projects don't need to start, simply configure `skip: true` for the specified project in `rsbuild.config.ts`.
+
+```ts
+// rsbuild.config.ts
+import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
+
+export default {
+  plugins: [
+    pluginWorkspaceDev({
+      projects: {
+        lib1: {
+          skip: true,
+        },
+      },
+    }),
+  ],
+};
+```
+
 ## License
 
 [MIT](./LICENSE).

package/README.zh-CN.md

@@ -16,7 +16,7 @@
 安装：
 
 ```bash
-npm add rsbuild-plugin-workspace-dev -D
+pnpm add rsbuild-plugin-workspace-dev -D
 ```
 
 在 `rsbuild.config.ts` 里注册插件:
@@ -78,12 +78,17 @@ lib2 依赖了 lib3：
 
 ## 选项
 
-### projectConfig
+### projects
 用于子项目的启动项配置和自定义日志匹配逻辑。
 
-- **类型：**:
+- **类型：**
 ```
-interface ProjectConfig {
+type projects = {
+  // key 为子项目 package.json name
+  [key: string]: Projects;
+}
+
+interface Projects {
   /**
    * 自定义子项目启动命令，默认值为 `dev`, 即执行 `npm run dev`。
    */
@@ -97,14 +102,26 @@ interface ProjectConfig {
    */
   skip?: boolean;
 }
+
+// 例如，配置 lib1 子项目，用 build:watch 命令启动，匹配 watch success 日志
+pluginWorkspaceDev({
+  projects: {
+    lib1: {
+      command: 'build:watch',
+      match: (stdout) => stdout.includes('watch success'),
+    },
+  },
+})
 ```
 
-### ignoreSelf
+
+### startCurrent
 
 - **类型：** `boolean`
-- **默认值：** `true`
-- 
-是否忽略当前项目的启动，默认值为 `true`。一般无需手动配置，当前项目通常由用户手动执行 dev 启动，无需插件干预。
+- **默认值：** `false`
+
+插件是否同时启动当前项目，默认值为 `false`。通常无需手动配置，当前项目通常由用户手动执行 dev 启动，无需插件干预。
+
 考虑如下场景，docs 和 lib 是在同一个项目中，而 docs 需要调试 lib 的产物，此时需要启动 `pnpm doc` 命令，而 lib 则需要启动 `pnpm dev` 命令，配置该选项到 rspress 配置中后，启动 `pnpm doc` 时会自动执行 `pnpm dev` 命令，用于启动 lib 子项目。
 ```
 ├── docs
@@ -127,24 +144,44 @@ interface ProjectConfig {
 - **类型：** `string`
 - **默认值：** `process.cwd()`
 
-用于配置当前工作目录，默认值为当前项目目录，一般无需配置。
+用于配置当前工作目录，默认值为当前项目目录，通常无需配置。
 
 ### workspaceFileDir
 
 - **类型：** `string`
 - **默认值：** `process.cwd()`
 
-用于配置 workspace 文件目录，默认值为当前项目目录，一般无需配置。
+用于配置 workspace 文件目录，默认值为当前项目目录，通常无需配置。
 
 
 ## 常见问题
 
-### 日志输出卡住
-这是由于子项目日志是启动完成后一次性输出的，卡住可能是因为子项目构建过慢等原因，可以通过添加环境变量来开启调试模式，查看当前处理到了哪个子项目卡住。如果长时间卡住，可以手动到子项目中执行 dev 命令查看是否。
+### 启动项目时卡住
+卡住可能是因为子项目构建过慢等原因，没有日志输出是因为默认情况下子项目日志是启动完成后一次性输出的（为了避免子项目日志混和在一起交错输出），可以通过添加环境变量来开启调试模式，这会让子项目的日志实时输出。
 ```
 DEBUG=rsbuild pnpm dev
 ```
 
+### 某些项目无需启动
+如果某些子项目不需要启动，只需要在 `rsbuild.config.ts` 中给指定项目配置 `skip: true` 即可。
+
+```ts
+// rsbuild.config.ts
+import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
+
+export default {
+  plugins: [
+    pluginWorkspaceDev({
+      projects: {
+        lib1: {
+          skip: true,
+        },
+      },
+    }),
+  ],
+};
+```
+
 
 ## License
 

package/dist/index.cjs

@@ -38,6 +38,11 @@ __webpack_require__.d(__webpack_exports__, {
 });
 const external_chalk_namespaceObject = require("chalk");
 var external_chalk_default = /*#__PURE__*/ __webpack_require__.n(external_chalk_namespaceObject);
+const PACKAGE_JSON = 'package.json';
+const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
+const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
+const MODERN_MODULE_READY_MESSAGE = 'Watching for file changes';
+const TSUP_READY_MESSAGE = 'Watching for changes in';
 const external_fs_namespaceObject = require("fs");
 var external_fs_default = /*#__PURE__*/ __webpack_require__.n(external_fs_namespaceObject);
 const external_json5_namespaceObject = require("json5");
@@ -53,11 +58,6 @@ const readJson = async (jsonFileAbsPath)=>{
 };
 const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
 const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
-const PACKAGE_JSON = 'package.json';
-const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
-const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
-const MODERN_MODULE_READY_MESSAGE = 'Watching for file changes';
-const TSUP_READY_MESSAGE = 'Watching for changes in';
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -179,7 +179,7 @@ class WorkspaceDevRunner {
         const promises = [];
         const allNodes = this.getNodes();
         const filterSelfNodes = allNodes.filter((node)=>node !== this.metaData.name);
-        const nodes = this.options.ignoreSelf ? filterSelfNodes : allNodes;
+        const nodes = this.options.startCurrent ? allNodes : filterSelfNodes;
         for (const node of nodes){
             const dependencies = this.getDependencies(node) || [];
             const canStart = dependencies.every((dep)=>{
@@ -202,7 +202,7 @@ class WorkspaceDevRunner {
             const logger = new Logger({
                 name
             });
-            const config = this.options?.projectConfig?.[name];
+            const config = this.options?.projects?.[name];
             if (config?.skip) {
                 this.visited[node] = true;
                 this.visiting[node] = false;
@@ -275,7 +275,7 @@ class WorkspaceDevRunner {
         workspace_dev_define_property(this, "matched", void 0);
         workspace_dev_define_property(this, "metaData", void 0);
         this.options = {
-            ignoreSelf: true,
+            startCurrent: false,
             ...options
         };
         this.cwd = options.cwd || process.cwd();

package/dist/index.js

@@ -5,6 +5,11 @@ import { getPackagesSync } from "@manypkg/get-packages";
 import { spawn } from "child_process";
 import graphlib, { Graph } from "graphlib";
 import path_0 from "path";
+const PACKAGE_JSON = 'package.json';
+const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
+const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
+const MODERN_MODULE_READY_MESSAGE = 'Watching for file changes';
+const TSUP_READY_MESSAGE = 'Watching for changes in';
 async function pathExists(path) {
     return fs.promises.access(path).then(()=>true).catch(()=>false);
 }
@@ -16,11 +21,6 @@ const readJson = async (jsonFileAbsPath)=>{
 };
 const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
 const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
-const PACKAGE_JSON = 'package.json';
-const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
-const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
-const MODERN_MODULE_READY_MESSAGE = 'Watching for file changes';
-const TSUP_READY_MESSAGE = 'Watching for changes in';
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -136,7 +136,7 @@ class WorkspaceDevRunner {
         const promises = [];
         const allNodes = this.getNodes();
         const filterSelfNodes = allNodes.filter((node)=>node !== this.metaData.name);
-        const nodes = this.options.ignoreSelf ? filterSelfNodes : allNodes;
+        const nodes = this.options.startCurrent ? allNodes : filterSelfNodes;
         for (const node of nodes){
             const dependencies = this.getDependencies(node) || [];
             const canStart = dependencies.every((dep)=>{
@@ -159,7 +159,7 @@ class WorkspaceDevRunner {
             const logger = new Logger({
                 name
             });
-            const config = this.options?.projectConfig?.[name];
+            const config = this.options?.projects?.[name];
             if (config?.skip) {
                 this.visited[node] = true;
                 this.visiting[node] = false;
@@ -232,7 +232,7 @@ class WorkspaceDevRunner {
         workspace_dev_define_property(this, "matched", void 0);
         workspace_dev_define_property(this, "metaData", void 0);
         this.options = {
-            ignoreSelf: true,
+            startCurrent: false,
             ...options
         };
         this.cwd = options.cwd || process.cwd();

package/dist/workspace-dev.d.ts

@@ -2,12 +2,12 @@ import graphlib from 'graphlib';
 export interface WorkspaceDevRunnerOptions {
     cwd?: string;
     workspaceFileDir?: string;
-    projectConfig?: Record<string, {
+    projects?: Record<string, {
         match?: (stdout: string) => boolean;
         command?: string;
         skip?: boolean;
     }>;
-    ignoreSelf?: boolean;
+    startCurrent?: boolean;
 }
 export declare class WorkspaceDevRunner {
     private options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsbuild-plugin-workspace-dev",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1",
   "description": "An Rsbuild plugin to provides workspace recursive dev functionality for Monorepo topologies.",
   "repository": "https://github.com/rspack-contrib/rsbuild-plugin-workspace-dev",
   "license": "MIT",