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

package/README.md

@@ -1 +1,197 @@
-# rsbuild-plugin-workspace-dev
+# rsbuild-plugin-workspace-dev
+
+Start monorepo sub-projects in topological order.
+
+`rsbuild-plugin-workspace-dev` is designed for monorepo development. It computes the dependency graph starting from the current project and starts sub-projects in topological order.
+
+<p>
+  <a href="https://npmjs.com/package/rsbuild-plugin-workspace-dev">
+   <img src="https://img.shields.io/npm/v/rsbuild-plugin-workspace-dev?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>
+
+English | [简体中文](./README.zh-CN.md)
+
+## Usage
+
+Install:
+
+```bash
+pnpm add rsbuild-plugin-workspace-dev -D
+```
+
+Register the plugin in `rsbuild.config.ts`:
+
+```ts
+// rsbuild.config.ts
+import { pluginWorkspaceDev } from "rsbuild-plugin-workspace-dev";
+
+export default {
+  plugins: [pluginWorkspaceDev()],
+};
+```
+
+## Use Cases
+
+In a monorepo, one project may depend on multiple sub-projects, and those sub-projects can also depend on each other.
+
+For example, the monorepo contains an app and several lib packages:
+
+```ts
+monorepo
+├── app
+└── lib1
+└── lib2
+└── lib3
+```
+
+Here, app is built with Rsbuild, and lib is built with Rslib. The app depends on lib1 and lib2:
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib1": "workspace:*",
+    "lib2": "workspace:*"
+  }
+}
+```
+
+lib2 depends on lib3:
+
+```json
+{
+  "name": "lib2",
+  "dependencies": {
+    "lib3": "workspace:*"
+  }
+}
+```
+
+When you run `pnpm dev` under app, sub-projects start in topological order: first lib1 and lib3, then lib2, and finally app. Starting a lib refers to running its dev command, for example:
+
+```json
+{
+  "scripts": {
+    "dev": "rslib build --watch"
+  }
+}
+```
+
+Whether a sub-project has finished starting is determined by matching sub-project logs. By default, logs from Rslib and tsup sub-projects are recognized. You can also provide a custom match function to determine when a sub-project is ready.
+
+## Options
+
+### projects
+Configure how sub-projects are started and define custom log matching logic.
+
+- Type:
+```
+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`).
+   */
+  command?: string;
+  /**
+   * Custom logic to detect when a sub-project has started.
+   * By default, logs from `Rsbuild` and `tsup` are supported.
+   */
+  match?: (stdout: string) => boolean;
+  /**
+   * Whether to skip starting the current sub-project. Default is `false`.
+   * Useful for sub-projects that do not need to be started.
+   */
+  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'),
+    },
+  },
+})
+```
+
+### startCurrent
+
+- Type: `boolean`
+- Default: `false`
+
+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.
+
+```
+├── docs
+│   └── index.mdx
+├── package.json
+├── src
+│   └── Button.tsx
+├── rslib.config.ts
+├── rspress.config.ts
+```
+
+```
+"scripts": {
+  "dev": "rslib build --watch",
+  "doc": "rspress dev"
+},
+```
+
+### cwd
+
+- Type: `string`
+- Default: `process.cwd()`
+
+Set the current working directory. The default is the current project directory; usually no configuration is needed.
+
+### workspaceFileDir
+
+- Type: `string`
+- Default: `process.cwd()`
+
+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,14 +144,44 @@ interface ProjectConfig {
 - **类型：** `string`
 - **默认值：** `process.cwd()`
 
-用于配置当前工作目录，默认值为当前项目目录，一般无需配置。
+用于配置当前工作目录，默认值为当前项目目录，通常无需配置。
 
 ### workspaceFileDir
 
 - **类型：** `string`
 - **默认值：** `process.cwd()`
 
-用于配置 workspace 文件目录，默认值为当前项目目录，一般无需配置。
+用于配置 workspace 文件目录，默认值为当前项目目录，通常无需配置。
+
+
+## 常见问题
+
+### 启动项目时卡住
+卡住可能是因为子项目构建过慢等原因，没有日志输出是因为默认情况下子项目日志是启动完成后一次性输出的（为了避免子项目日志混和在一起交错输出），可以通过添加环境变量来开启调试模式，这会让子项目的日志实时输出。
+```
+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

@@ -43,6 +43,21 @@ 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");
+var external_json5_default = /*#__PURE__*/ __webpack_require__.n(external_json5_namespaceObject);
+async function pathExists(path) {
+    return external_fs_default().promises.access(path).then(()=>true).catch(()=>false);
+}
+const readJson = async (jsonFileAbsPath)=>{
+    if (!await pathExists(jsonFileAbsPath)) return {};
+    const content = await external_fs_default().promises.readFile(jsonFileAbsPath, 'utf-8');
+    const json = external_json5_default().parse(content);
+    return json;
+};
+const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
+const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -76,6 +91,7 @@ class Logger {
         this.stdout = startBanner + this.stdout;
     }
     flushStdout() {
+        if (isDebug) return;
         this.setBanner(this.name);
         this.emitLog("stdout");
     }
@@ -94,9 +110,8 @@ class Logger {
         this.logTitle = DEBUG_LOG_TITLE;
     }
 }
-const debugLog = (msg)=>{
-    const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
-    if (isDebug) console.log(DEBUG_LOG_TITLE + msg);
+const debugLog = (msg, prefix = DEBUG_LOG_TITLE)=>{
+    if (isDebug) console.log(prefix + msg);
 };
 const get_packages_namespaceObject = require("@manypkg/get-packages");
 const external_child_process_namespaceObject = require("child_process");
@@ -104,20 +119,6 @@ const external_graphlib_namespaceObject = require("graphlib");
 var external_graphlib_default = /*#__PURE__*/ __webpack_require__.n(external_graphlib_namespaceObject);
 const external_path_namespaceObject = require("path");
 var external_path_default = /*#__PURE__*/ __webpack_require__.n(external_path_namespaceObject);
-const external_fs_namespaceObject = require("fs");
-var external_fs_default = /*#__PURE__*/ __webpack_require__.n(external_fs_namespaceObject);
-const external_json5_namespaceObject = require("json5");
-var external_json5_default = /*#__PURE__*/ __webpack_require__.n(external_json5_namespaceObject);
-async function pathExists(path) {
-    return external_fs_default().promises.access(path).then(()=>true).catch(()=>false);
-}
-const readJson = async (jsonFileAbsPath)=>{
-    if (!await pathExists(jsonFileAbsPath)) return {};
-    const content = await external_fs_default().promises.readFile(jsonFileAbsPath, 'utf-8');
-    const json = external_json5_default().parse(content);
-    return json;
-};
-const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
 function workspace_dev_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -178,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)=>{
@@ -201,12 +202,11 @@ 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;
                 debugLog(`Skip visit node: ${node}`);
-                logger.flushStdout();
                 logger.emitLogOnce('stdout', `skip visit node: ${name}`);
                 return this.start().then(()=>resolve());
             }
@@ -224,11 +224,9 @@ class WorkspaceDevRunner {
             });
             child.stdout.on('data', async (data)=>{
                 const stdout = data.toString();
-                if (this.matched[node]) {
-                    const content = data.toString().replace(/\n$/, '');
-                    logger.emitLogOnce('stdout', content);
-                    return;
-                }
+                const content = data.toString().replace(/\n$/, '');
+                if (this.matched[node]) return void logger.emitLogOnce('stdout', content);
+                debugLog(content, `${name}: `);
                 logger.appendLog('stdout', stdout);
                 const match = config?.match;
                 const matchResult = match ? match(stdout) : stdout.match(RSLIB_READY_MESSAGE) || stdout.match(MODERN_MODULE_READY_MESSAGE) || stdout.match(TSUP_READY_MESSAGE);
@@ -277,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

@@ -1,15 +1,26 @@
 import chalk from "chalk";
+import fs from "fs";
+import json5 from "json5";
 import { getPackagesSync } from "@manypkg/get-packages";
 import { spawn } from "child_process";
 import graphlib, { Graph } from "graphlib";
 import path_0 from "path";
-import fs from "fs";
-import json5 from "json5";
 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);
+}
+const readJson = async (jsonFileAbsPath)=>{
+    if (!await pathExists(jsonFileAbsPath)) return {};
+    const content = await fs.promises.readFile(jsonFileAbsPath, 'utf-8');
+    const json = json5.parse(content);
+    return json;
+};
+const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
+const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -43,6 +54,7 @@ class Logger {
         this.stdout = startBanner + this.stdout;
     }
     flushStdout() {
+        if (isDebug) return;
         this.setBanner(this.name);
         this.emitLog("stdout");
     }
@@ -61,20 +73,9 @@ class Logger {
         this.logTitle = DEBUG_LOG_TITLE;
     }
 }
-const debugLog = (msg)=>{
-    const isDebug = 'rsbuild' === process.env.DEBUG || '*' === process.env.DEBUG;
-    if (isDebug) console.log(DEBUG_LOG_TITLE + msg);
-};
-async function pathExists(path) {
-    return fs.promises.access(path).then(()=>true).catch(()=>false);
-}
-const readJson = async (jsonFileAbsPath)=>{
-    if (!await pathExists(jsonFileAbsPath)) return {};
-    const content = await fs.promises.readFile(jsonFileAbsPath, 'utf-8');
-    const json = json5.parse(content);
-    return json;
+const debugLog = (msg, prefix = DEBUG_LOG_TITLE)=>{
+    if (isDebug) console.log(prefix + msg);
 };
-const readPackageJson = async (pkgJsonFilePath)=>readJson(pkgJsonFilePath);
 function workspace_dev_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -135,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)=>{
@@ -158,12 +159,11 @@ 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;
                 debugLog(`Skip visit node: ${node}`);
-                logger.flushStdout();
                 logger.emitLogOnce('stdout', `skip visit node: ${name}`);
                 return this.start().then(()=>resolve());
             }
@@ -181,11 +181,9 @@ class WorkspaceDevRunner {
             });
             child.stdout.on('data', async (data)=>{
                 const stdout = data.toString();
-                if (this.matched[node]) {
-                    const content = data.toString().replace(/\n$/, '');
-                    logger.emitLogOnce('stdout', content);
-                    return;
-                }
+                const content = data.toString().replace(/\n$/, '');
+                if (this.matched[node]) return void logger.emitLogOnce('stdout', content);
+                debugLog(content, `${name}: `);
                 logger.appendLog('stdout', stdout);
                 const match = config?.match;
                 const matchResult = match ? match(stdout) : stdout.match(RSLIB_READY_MESSAGE) || stdout.match(MODERN_MODULE_READY_MESSAGE) || stdout.match(TSUP_READY_MESSAGE);
@@ -234,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/logger.d.ts

@@ -14,4 +14,4 @@ export declare class Logger {
     flushStdout(): void;
     static setEndBanner(): void;
 }
-export declare const debugLog: (msg: string) => void;
+export declare const debugLog: (msg: string, prefix?: string) => void;

package/dist/utils.d.ts

@@ -1,3 +1,4 @@
 import type { Package } from '@manypkg/get-packages';
 export declare const readJson: <T>(jsonFileAbsPath: string) => Promise<T>;
 export declare const readPackageJson: (pkgJsonFilePath: string) => Promise<Package["packageJson"]>;
+export declare const isDebug: boolean;

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.0",
+  "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",