signalk-container-helper 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# v0.2.2
+
+Maintenance release — dependency updates only, no changes to the library's public API or runtime behaviour.
+
+- **TypeScript 6** — the dev toolchain moves from `^5.5.0` to `^6.0.3`; the emitted declarations and ESM output are unchanged, and the full build, 96-test suite, and lint chain pass under the new compiler
+- **`signalk-container` type source bumped 1.23.2 → 1.25.2** — the contract test that pins this library's type mirror against `signalk-container/types` still passes, so the mirrored `ContainerManagerApi` / `ContainerConfig` / `UpdateServiceApi` surface has not drifted against the newer manager
+- Dev-dependency refresh: `eslint` 10.7.0 → 10.8.0, `typescript-eslint` 8.65.0 → 8.66.0, `globals` 17.7.0 → 17.9.0, `@types/react` 19.2.17 → 19.2.18
+- CI: `actions/checkout` and `actions/setup-node` bumped to v7 in the publish workflow
+
+# v0.2.1
+
+Docs-only release.
+
+- **README: "ESM plugins must build an ESM remote"** — Signal K injects each configurator panel's script tag based on the plugin's package.json `type` field, so `"type": "module"` plugins (like this library, and therefore most of its consumers) must build their panel as an ESM Module Federation container (`experiments.outputModule` + `output.module` + `library: { type: "module" }`); the classic `var` remote the CommonJS reference plugins use loads silently into module scope and fails at panel-open time with the misleading _'Module "…" is not available. Make sure the webapp is installed.'_ The new section documents the server's injection logic, both mismatch failure modes, the webpack recipe, a `get`/`init` verification one-liner, and links [signalk-piper](https://github.com/hoeken/signalk-piper) as a working ESM example — plus a matching panel-conventions bullet, and the "no changes to the standard webpack config" claim is now scoped to loaders
+
 # v0.2.0
 
 - **New `signalk-container-helper/ui` entrypoint** — browser-side React building blocks for plugin config panels, packaging the pieces the reference plugins (`signalk-grafana`, `signalk-questdb`, `mayara-server-signalk-plugin`) had each been hand-copying: the shared inline-style vocabulary (`panelStyles`, `stateColors`), components (`StatusCard`, `VersionSelect`, `UpdateControls`, `Button`, `CollapsibleSection`, and friends), fetch-and-poll hooks (`useStatusPoll`, `useVersions`, `useUpdateFlow`) with self-scheduling polls and stale-response drops, version-dropdown view logic (`deriveVersionsView`) that handles both structured and legacy `/api/versions` shapes and falls back to the running tag so a rate-limited GitHub fetch never blanks the select, and `formatUpdateMessage` typed against `UpdateCheckResult` to match `registerUpdateRoutes`' contract

package/README.md

@@ -222,8 +222,9 @@ shared as a singleton). The standard webpack config runs `babel-loader` with
 `exclude: /node_modules/`, so a library shipping raw JSX would break the
 build. This entrypoint therefore ships **tsc-compiled `React.createElement`
 JS (no JSX)** that webpack bundles directly, and its `import "react"` resolves
-to the host Admin UI's shared React singleton. No changes to the standard
-webpack config are needed.
+to the host Admin UI's shared React singleton. No loader changes are needed —
+but the remote's output format must match your package's module type (next
+section).
 
 ```bash
 npm install signalk-container-helper react
@@ -232,6 +233,68 @@ npm install signalk-container-helper react
 (`react` can be a devDependency of your plugin — it is only used at bundle
 time; at runtime the Admin UI provides the singleton.)
 
+### ESM plugins must build an ESM remote
+
+The server injects each panel's script tag based on the **plugin's**
+package.json `type` field:
+
+```js
+moduleInfo.type === "module"
+  ? `<script type="module" src="/${moduleInfo.name}/remoteEntry.js"></script>`
+  : `<script src="/${moduleInfo.name}/remoteEntry.js"></script>`;
+```
+
+The remote's output format must match, and the failure modes on a mismatch
+are unhelpful, so get this right up front:
+
+- **CommonJS plugin** (the reference plugins): the classic remote —
+  `library: { type: "var", name: "<name with [-@/] → _>" }` — which lands on
+  `window` when the plain script tag runs.
+- **`"type": "module"` plugin** (likely yours — this library is ESM-only):
+  the Admin UI loads the panel with a dynamic `import()` and requires real
+  `get`/`init` module exports. A copied `var` remote loads silently into
+  module scope — no window global, no exports — and the panel dies with
+  _'Module "…" is not available. Make sure the webapp is installed.'_ even
+  though discovery and serving worked. Build an **ESM container** instead:
+
+  ```js
+  // webpack.config.cjs (an ESM package needs the .cjs extension, or an ESM config)
+  module.exports = {
+    // ...
+    experiments: { outputModule: true },
+    output: {
+      path: path.resolve(__dirname, "public"),
+      module: true,
+      clean: false,
+    },
+    plugins: [
+      new ModuleFederationPlugin({
+        name: "your_plugin_name",
+        library: { type: "module" }, // no global var name
+        filename: "remoteEntry.js",
+        exposes: {
+          "./PluginConfigurationPanel":
+            "./src/configpanel/PluginConfigurationPanel",
+        },
+        shared: {
+          react: { singleton: true, requiredVersion: "^19" },
+          "react-dom": { singleton: true, requiredVersion: "^19" },
+        },
+      }),
+    ],
+  };
+  ```
+
+  Chunks emit as `.mjs`; verify the container shape with
+  `node -e 'import("./public/remoteEntry.js").then((m) => console.log(typeof m.get, typeof m.init))'`
+  (both must print `function`).
+
+The mismatch breaks in the other direction too: a CJS package emitting an ESM
+remote throws a `SyntaxError` when the browser executes `export` syntax from
+a plain script tag. A working ESM example is
+[signalk-piper](https://github.com/hoeken/signalk-piper)'s
+`webpack.config.cjs`.
+
 ### Example panel
 
 ```jsx
@@ -360,6 +423,11 @@ Adopt these even where you don't use the components:
   checked 3h ago", don't paint the panel red.
 - **Persist the requested tag, not the resolved one** after an update, so
   floating tags like `latest` keep auto-tracking.
+- **Match the remote's module format to your package's `type` field.** The
+  server injects `<script type="module">` for `"type": "module"` plugins and
+  a plain script tag otherwise; the wrong webpack `library` type fails only
+  at panel-open time, with a misleading "webapp is not installed" error (see
+  [ESM plugins must build an ESM remote](#esm-plugins-must-build-an-esm-remote)).
 
 ## API overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-container-helper",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Helper library for Signal K plugins that manage containers via the signalk-container plugin",
   "type": "module",
   "main": "dist/index.js",
@@ -75,7 +75,7 @@
     "globals": "^17.4.0",
     "prettier": "^3.8.1",
     "signalk-container": "^1.23.2",
-    "typescript": "^5.5.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.58.0",
     "vitest": "^4.1.10"
   }