rsbuild-plugin-devtools-json 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# rsbuild-plugin-devtools-json
+
+Rsbuild plugin for generating the Chrome DevTools project settings file on-the-fly in the dev server.
+
+<p>
+  <a href="https://npmjs.com/package/rsbuild-plugin-devtools-json">
+   <img src="https://img.shields.io/npm/v/rsbuild-plugin-devtools-json?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>
+
+This enables seamless integration with the new Chrome DevTools features:
+
+1. [DevTools Project Settings (devtools.json)](https://goo.gle/devtools-json-design)
+2. [Automatic Workspace folders](http://goo.gle/devtools-automatic-workspace-folders)
+
+<img width="800" alt="Screenshot 2025-06-22 at 21 45 26" src="https://github.com/user-attachments/assets/daae3e57-f0fc-43c1-b191-8f916bc542ae" />
+
+## Installation
+
+```bash
+npm i -D rsbuild-plugin-devtools-json
+```
+
+## Usage
+
+Add it to your Rsbuild config:
+
+```js
+import { defineConfig } from "@rsbuild/core";
+import { pluginDevtoolsJson } from "rsbuild-plugin-devtools-json";
+
+export default defineConfig({
+  plugins: [
+    pluginDevtoolsJson(),
+    // ...
+  ],
+});
+```
+
+While the plugin can generate a UUID and save it in Rsbuild cache, you can also specify it in the options like in the following:
+
+```js
+pluginDevtoolsJson({
+  uuid: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
+});
+```
+
+You can also specify a custom root path for the DevTools project settings:
+
+```js
+pluginDevtoolsJson({
+  rootPath: "/path/to/custom/root",
+});
+```
+
+This is particularly useful in monorepo setups, where you might want to set the root path to the monorepo root directory, especially when used with [rsbuild-plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build). If not provided, the default root path from Rsbuild context will be used.
+
+The `/.well-known/appspecific/com.chrome.devtools.json` endpoint will serve the project settings as JSON with the following structure:
+
+```json
+{
+  "workspace": {
+    "root": "/path/to/project/root",
+    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
+  }
+}
+```
+
+Here `root` is the absolute path to your `{projectRoot}` folder, and `uuid` is a random v4 UUID, generated the first time that you start the Rsbuild dev server with the plugin installed (it is henceforth cached in the Rsbuild cache folder).
+
+## Credits
+
+This plugin is inspired by [vite-plugin-devtools-json](https://github.com/ChromeDevTools/vite-plugin-devtools-json). Both the implementation and documentation have been adapted and referenced from the original Vite plugin.
+
+## License
+
+The code is under [MIT License](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { RsbuildPlugin } from '@rsbuild/core';
+declare const plugin: (options?: {
+    uuid: string;
+}) => RsbuildPlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,55 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { v4, validate } from "uuid";
+const ENDPOINT = '/.well-known/appspecific/com.chrome.devtools.json';
+const src_plugin = (options)=>({
+        name: 'rsbuild-plugin-devtools-json',
+        setup (api) {
+            if ('development' !== process.env.NODE_ENV) return;
+            const getOrCreateUUID = ()=>{
+                if (options?.uuid) return options.uuid;
+                const cacheDir = api.context.cachePath;
+                const uuidPath = node_path.resolve(cacheDir, 'uuid.json');
+                if (node_fs.existsSync(uuidPath)) {
+                    const uuid = node_fs.readFileSync(uuidPath, {
+                        encoding: 'utf-8'
+                    });
+                    if (validate(uuid)) return uuid;
+                }
+                if (!node_fs.existsSync(cacheDir)) node_fs.mkdirSync(cacheDir, {
+                    recursive: true
+                });
+                const uuid = v4();
+                node_fs.writeFileSync(uuidPath, uuid, {
+                    encoding: 'utf-8'
+                });
+                console.log(`[rsbuild-plugin-devtools-json] Generated UUID '${uuid}' for DevTools project settings.`);
+                return uuid;
+            };
+            api.modifyRsbuildConfig((userConfig, { mergeRsbuildConfig })=>mergeRsbuildConfig(userConfig, {
+                    dev: {
+                        setupMiddlewares: [
+                            (middlewares)=>{
+                                middlewares.push((req, res, next)=>{
+                                    if (req.url !== ENDPOINT) return next();
+                                    let root = api.context.rootPath;
+                                    if (process.env.WSL_DISTRO_NAME) root = node_path.join('\\\\wsl.localhost', process.env.WSL_DISTRO_NAME, root).replace(/\//g, '\\');
+                                    const uuid = getOrCreateUUID();
+                                    const devtoolsJson = {
+                                        workspace: {
+                                            root,
+                                            uuid
+                                        }
+                                    };
+                                    res.setHeader('Content-Type', 'application/json');
+                                    res.end(JSON.stringify(devtoolsJson, null, 2));
+                                });
+                                return middlewares;
+                            }
+                        ]
+                    }
+                }));
+        }
+    });
+const src = src_plugin;
+export { src as default };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "rsbuild-plugin-devtools-json",
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.0.4",
+    "@rslib/core": "0.10.2",
+    "@types/node": "24.0.3",
+    "typescript": "5.8.3"
+  },
+  "peerDependencies": {
+    "@rsbuild/core": "^1"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "lint": "biome check",
+    "lint:write": "biome check . --write",
+    "dev": "rslib build --watch",
+    "format": "biome format --write",
+    "bump": "npx bumpp"
+  }
+}