@ichicraft/widgets-widget-base 1.19.0 → 1.20.0

package/README.md

@@ -9,6 +9,15 @@ All notable changes to this project will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.20.0 - 2026-08-25
+
+-   Added `createWidgetDevServerConfig` and `findAvailablePort`, exported from `@ichicraft/widgets-widget-base/lib/dev` for use in a widget's `webpack.dev.ts`. The helper resolves a free port before it builds the debug url, so the manifest url handed to the board always matches the port the dev server binds to. This is what allows several widgets to be served and debugged on the same board at the same time.
+-   Added `cssModuleLocalIdentName` to the result of `createWidgetDevServerConfig`. It is keyed by port, so css module class names stay unique between widgets that are served at the same time.
+-   Added optional `debugPort` property to `WidgetDebugServeConfig`, pinning a widget's dev server to a fixed port. When omitted, the first free port from 8080 upwards is used.
+-   Added optional `openBrowser` property to `WidgetDebugServeConfig`. Set it to `false` for the second and further widgets in a multi-widget debug session, so they serve their bundle without opening a browser window of their own.
+-   Added `webpack` and `webpack-dev-server` as optional peer dependencies. They are only needed when using the `lib/dev` helpers, which every widget project already has installed.
+-   **Breaking:** removed the `DebugComponentType` enum and the `debugComponentType` property of `WidgetDebugServeConfig`. Opening the board on one specific component no longer makes sense now that several widgets can be debugged at once. Remove both from your `config/serve.config.ts`.
+
 ## 1.19.0 - 2026-08-18
 
 -   Added optional `bloomGroups` provider to `WidgetContext`, exposing a `fetchGroups()` function that supplies the tenant's Bloom Group definitions. Widgets can pass it through to their people pickers so Bloom Groups can be offered as suggestions.

package/lib/dev/createWidgetDevServerConfig.d.ts

@@ -0,0 +1,31 @@
+import type { Configuration as DevServerConfiguration } from 'webpack-dev-server';
+import type { WidgetDebugServeConfig } from '../types';
+/** Port the first widget dev server claims. Later ones move up from here. */
+export declare const DEFAULT_WIDGET_DEBUG_PORT = 8080;
+export interface CreateWidgetDevServerConfigOptions {
+    /** Root folder of the widget project, normally `__dirname` from webpack.dev.ts. */
+    projectPath: string;
+    /** The widget's `config/serve.config.ts` export. */
+    serveConfig: WidgetDebugServeConfig;
+}
+export interface WidgetDevServerConfigResult {
+    /** The port the dev server will listen on. */
+    port: number;
+    devServer: DevServerConfiguration;
+    /**
+     * Value for the css-loader `localIdentName` option. Keyed by port so two widgets served at
+     * the same time -- and the CDN build of the same widget -- never share a class name.
+     */
+    cssModuleLocalIdentName: string;
+    /** Where the board fetches this widget's manifest from. */
+    manifestUrl: string;
+    /** The board url that gets opened, or null when no debug page is configured. */
+    debugPageUrl: string | null;
+}
+/**
+ * Builds the dev server configuration for debugging a widget against a live widget board.
+ *
+ * The port is resolved at config time rather than hardcoded, so the manifest url handed to the
+ * board always matches the port the server actually binds to.
+ */
+export declare function createWidgetDevServerConfig(options: CreateWidgetDevServerConfigOptions): Promise<WidgetDevServerConfigResult>;

package/lib/dev/createWidgetDevServerConfig.js

@@ -0,0 +1,92 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWidgetDevServerConfig = exports.DEFAULT_WIDGET_DEBUG_PORT = void 0;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+const findAvailablePort_1 = require("./findAvailablePort");
+/** Port the first widget dev server claims. Later ones move up from here. */
+exports.DEFAULT_WIDGET_DEBUG_PORT = 8080;
+/**
+ * Builds the dev server configuration for debugging a widget against a live widget board.
+ *
+ * The port is resolved at config time rather than hardcoded, so the manifest url handed to the
+ * board always matches the port the server actually binds to.
+ */
+function createWidgetDevServerConfig(options) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const { projectPath, serveConfig } = options;
+        const port = (_a = serveConfig.debugPort) !== null && _a !== void 0 ? _a : (yield (0, findAvailablePort_1.findAvailablePort)(exports.DEFAULT_WIDGET_DEBUG_PORT));
+        const manifestUrl = `https://localhost:${port}/manifest.json`;
+        let debugPageUrl = null;
+        if (serveConfig.widgetsDebugPageUrl && serveConfig.openBrowser !== false) {
+            const serveUrl = new url_1.URL(serveConfig.widgetsDebugPageUrl);
+            serveUrl.searchParams.append('debugWidgetManifest', manifestUrl);
+            debugPageUrl = serveUrl.href;
+        }
+        return {
+            port,
+            manifestUrl,
+            debugPageUrl,
+            cssModuleLocalIdentName: `[local]_${port}`,
+            devServer: {
+                static: path_1.default.join(projectPath, './dist'),
+                port,
+                host: 'localhost',
+                allowedHosts: 'all',
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                },
+                client: {
+                    overlay: false,
+                },
+                server: {
+                    type: 'https',
+                    options: resolveDevCertificate(),
+                },
+                open: debugPageUrl
+                    ? {
+                        target: [debugPageUrl],
+                        app: {
+                            name: 'google-chrome',
+                            arguments: ['--incognito', '--new-window'],
+                        },
+                    }
+                    : false,
+                devMiddleware: {
+                    writeToDisk: true,
+                },
+            },
+        };
+    });
+}
+exports.createWidgetDevServerConfig = createWidgetDevServerConfig;
+/**
+ * Uses the SPFx localhost certificate that was trusted with `gulp trust-dev-cert`,
+ * falling back to the rushstack certificate on newer toolchains.
+ */
+function resolveDevCertificate() {
+    const gcbCert = path_1.default.join(os_1.default.homedir(), '.gcb-serve-data', 'gcb-serve.cer');
+    const gcbKey = path_1.default.join(os_1.default.homedir(), '.gcb-serve-data', 'gcb-serve.key');
+    if (fs_1.default.existsSync(gcbCert) && fs_1.default.existsSync(gcbKey)) {
+        return { cert: fs_1.default.readFileSync(gcbCert), key: fs_1.default.readFileSync(gcbKey) };
+    }
+    return {
+        cert: fs_1.default.readFileSync(path_1.default.join(os_1.default.homedir(), '.rushstack', 'rushstack-serve.pem')),
+        key: fs_1.default.readFileSync(path_1.default.join(os_1.default.homedir(), '.rushstack', 'rushstack-serve.key')),
+    };
+}

package/lib/dev/findAvailablePort.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves the first free TCP port at or above `startPort`, so several widget dev servers
+ * can run side by side without anyone having to hand out port numbers.
+ */
+export declare function findAvailablePort(startPort: number, attempts?: number): Promise<number>;

package/lib/dev/findAvailablePort.js

@@ -0,0 +1,55 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePort = void 0;
+const net_1 = __importDefault(require("net"));
+/** Both loopback stacks are checked: a dev server on one of them still owns the port. */
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * Resolves the first free TCP port at or above `startPort`, so several widget dev servers
+ * can run side by side without anyone having to hand out port numbers.
+ */
+function findAvailablePort(startPort, attempts = 50) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (let port = startPort; port < startPort + attempts; port++) {
+            if (yield isPortAvailable(port)) {
+                return port;
+            }
+        }
+        throw new Error(`[widgets-widget-base] No free port found between ${startPort} and ${startPort + attempts - 1}. Stop a running dev server or set "debugPort" in config/serve.config.ts.`);
+    });
+}
+exports.findAvailablePort = findAvailablePort;
+function isPortAvailable(port) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const host of LOOPBACK_HOSTS) {
+            if (!(yield isPortAvailableOnHost(port, host))) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+function isPortAvailableOnHost(port, host) {
+    return new Promise((resolve) => {
+        const server = net_1.default.createServer();
+        server.once('error', (err) => {
+            // Anything other than "taken" means we can't bind this stack at all (no IPv6, for
+            // example), which says nothing about whether the port is free.
+            resolve(err.code !== 'EADDRINUSE');
+        });
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}

package/lib/dev/index.d.ts

@@ -0,0 +1,2 @@
+export { createWidgetDevServerConfig, DEFAULT_WIDGET_DEBUG_PORT, type CreateWidgetDevServerConfigOptions, type WidgetDevServerConfigResult, } from './createWidgetDevServerConfig';
+export { findAvailablePort } from './findAvailablePort';

package/lib/dev/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePort = exports.DEFAULT_WIDGET_DEBUG_PORT = exports.createWidgetDevServerConfig = void 0;
+var createWidgetDevServerConfig_1 = require("./createWidgetDevServerConfig");
+Object.defineProperty(exports, "createWidgetDevServerConfig", { enumerable: true, get: function () { return createWidgetDevServerConfig_1.createWidgetDevServerConfig; } });
+Object.defineProperty(exports, "DEFAULT_WIDGET_DEBUG_PORT", { enumerable: true, get: function () { return createWidgetDevServerConfig_1.DEFAULT_WIDGET_DEBUG_PORT; } });
+var findAvailablePort_1 = require("./findAvailablePort");
+Object.defineProperty(exports, "findAvailablePort", { enumerable: true, get: function () { return findAvailablePort_1.findAvailablePort; } });

package/lib/types/index.d.ts

@@ -705,17 +705,6 @@ export interface WidgetManifestConfig {
         }[];
     };
 }
-export declare enum DebugComponentType {
-    /**
-     * This is the default component type and just opens the default widget board.
-     */
-    Default = "Default",
-    /**
-     * This automatically opens the widget board administration panel and opens the widget admin config
-     * dialog of the widget you're working on
-     */
-    AdminConfig = "AdminConfig"
-}
 /**
  * The widget debug serve config contains settings for debugging a widget in development
  */
@@ -726,11 +715,16 @@ export interface WidgetDebugServeConfig {
      */
     widgetsDebugPageUrl: string;
     /**
-     * Provide a component type to open the debugging widget board with that specific component.
-     * This speeds up your development cycle: [npm run start] > save changes > builds automatically >
-     * refresh browser > automatically open updated component.
+     * Pin the dev server to a specific port. When omitted, the first free port from 8080 upwards
+     * is used, so several widgets can be debugged side by side without configuration.
+     */
+    debugPort?: number;
+    /**
+     * Open the widget board in a browser when the dev server starts. Defaults to true.
+     * Set this to false for the second and further widgets in a multi-widget debug session:
+     * they only need to serve their bundle and are registered from the board that is already open.
      */
-    debugComponentType?: DebugComponentType;
+    openBrowser?: boolean;
 }
 /**
  * Tells the severity of the command bar item, resulting in

package/lib/types/index.js

@@ -1,18 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = exports.DebugComponentType = void 0;
-var DebugComponentType;
-(function (DebugComponentType) {
-    /**
-     * This is the default component type and just opens the default widget board.
-     */
-    DebugComponentType["Default"] = "Default";
-    /**
-     * This automatically opens the widget board administration panel and opens the widget admin config
-     * dialog of the widget you're working on
-     */
-    DebugComponentType["AdminConfig"] = "AdminConfig";
-})(DebugComponentType || (exports.DebugComponentType = DebugComponentType = {}));
+exports.CommandBarItemType = exports.CustomCommandBarItemSeverity = void 0;
 /**
  * Tells the severity of the command bar item, resulting in
  * distinguishable presentation of the item

package/package.json

@@ -1,45 +1,61 @@
-{
-    "name": "@ichicraft/widgets-widget-base",
-    "version": "1.19.0",
-    "description": "Part of the Widget Development Kit for building widgets for Bloom Intranet",
-    "main": "lib/index.js",
-    "types": "lib/index.d.ts",
-    "scripts": {
-        "build": "tsc --build --force --verbose",
-        "build:watch": "tsc  --build --force --verbose --watch",
-        "clean": "rimraf lib",
-        "pretty": "prettier --write \"./**/*.{js,jsx,mjs,cjs,ts,tsx,json}\"",
-        "prepublishOnly": "npm run clean && npm run build"
-    },
-    "keywords": [
-        "ichicraft",
-        "widget",
-        "widgets"
-    ],
-    "author": "Ichicraft",
-    "license": "UNLICENSED",
-    "files": [
-        "lib/**/*"
-    ],
-    "overrides": {
-        "requirejs": "2.3.7",
-        "validator@<13.15.26": "13.15.26",
-        "z-schema@<5.0.5": "5.0.5"
-    },
-    "dependencies": {
-        "@ichicraft/caching": "~1.0.2",
-        "@microsoft/microsoft-graph-client": "3.0.2",
-        "@microsoft/sp-http": "1.18.2",
-        "@pnp/sp": "4.0.1"
-    },
-    "devDependencies": {
-        "@ianvs/prettier-plugin-sort-imports": "4.4.1",
-        "eslint": "8.57.0",
-        "eslint-config-prettier": "9.1.0",
-        "eslint-plugin-prettier": "5.2.1",
-        "eslint-plugin-react": "7.35.2",
-        "eslint-plugin-react-hooks": "4.6.2",
-        "prettier": "3.3.3",
-        "typescript": "~5.3.3"
-    }
-}
+{
+    "name": "@ichicraft/widgets-widget-base",
+    "version": "1.20.0",
+    "description": "Part of the Widget Development Kit for building widgets for Bloom Intranet",
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "scripts": {
+        "build": "tsc --build --force --verbose tsconfig.json tsconfig.dev.json",
+        "build:watch": "tsc --build --force --verbose --watch tsconfig.json tsconfig.dev.json",
+        "clean": "rimraf lib",
+        "pretty": "prettier --write \"./**/*.{js,jsx,mjs,cjs,ts,tsx,json}\"",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "keywords": [
+        "ichicraft",
+        "widget",
+        "widgets"
+    ],
+    "author": "Ichicraft",
+    "license": "UNLICENSED",
+    "files": [
+        "lib/**/*",
+        "!lib/**/*.tsbuildinfo"
+    ],
+    "overrides": {
+        "requirejs": "2.3.7",
+        "validator@<13.15.26": "13.15.26",
+        "z-schema@<5.0.5": "5.0.5"
+    },
+    "dependencies": {
+        "@ichicraft/caching": "~1.0.2",
+        "@microsoft/microsoft-graph-client": "3.0.2",
+        "@microsoft/sp-http": "1.18.2",
+        "@pnp/sp": "4.0.1"
+    },
+    "devDependencies": {
+        "@ianvs/prettier-plugin-sort-imports": "4.4.1",
+        "@types/node": "^18.19.0",
+        "eslint": "8.57.0",
+        "eslint-config-prettier": "9.1.0",
+        "eslint-plugin-prettier": "5.2.1",
+        "eslint-plugin-react": "7.35.2",
+        "eslint-plugin-react-hooks": "4.6.2",
+        "prettier": "3.3.3",
+        "typescript": "~5.3.3",
+        "webpack": "^5.109.2",
+        "webpack-dev-server": "^5.2.6"
+    },
+    "peerDependencies": {
+        "webpack": "^5.0.0",
+        "webpack-dev-server": "^5.0.0"
+    },
+    "peerDependenciesMeta": {
+        "webpack": {
+            "optional": true
+        },
+        "webpack-dev-server": {
+            "optional": true
+        }
+    }
+}