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

package/README.md

@@ -1 +1,149 @@
-# 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>
+
+## Usage
+
+Install:
+
+```bash
+npm 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
+
+### projectConfig
+Configure how sub-projects are started and define custom log matching logic.
+
+- Type:
+```
+interface ProjectConfig {
+  /**
+   * 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;
+}
+```
+
+### ignoreSelf
+
+- Type: `boolean`
+- Default: `true`
+
+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.
+
+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.
+
+## License
+
+[MIT](./LICENSE).

package/README.zh-CN.md

@@ -136,6 +136,16 @@ interface ProjectConfig {
 
 用于配置 workspace 文件目录，默认值为当前项目目录，一般无需配置。
 
+
+## 常见问题
+
+### 日志输出卡住
+这是由于子项目日志是启动完成后一次性输出的，卡住可能是因为子项目构建过慢等原因，可以通过添加环境变量来开启调试模式，查看当前处理到了哪个子项目卡住。如果长时间卡住，可以手动到子项目中执行 dev 命令查看是否。
+```
+DEBUG=rsbuild pnpm dev
+```
+
+
 ## License
 
 [MIT](./LICENSE).

package/dist/index.cjs

@@ -38,6 +38,21 @@ __webpack_require__.d(__webpack_exports__, {
 });
 const external_chalk_namespaceObject = require("chalk");
 var external_chalk_default = /*#__PURE__*/ __webpack_require__.n(external_chalk_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);
+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';
@@ -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,
@@ -206,7 +207,6 @@ class WorkspaceDevRunner {
                 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);

package/dist/index.js

@@ -1,10 +1,21 @@
 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";
+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;
 const PACKAGE_JSON = 'package.json';
 const DEBUG_LOG_TITLE = '[Rsbuild Workspace Dev Plugin]: ';
 const RSLIB_READY_MESSAGE = 'build complete, watching for changes';
@@ -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,
@@ -163,7 +164,6 @@ class WorkspaceDevRunner {
                 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);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsbuild-plugin-workspace-dev",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.1-beta.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",