@reliantlabs/forge-web-runtime 0.7.0 → 0.8.0

package/dist/vite.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * The environment variable `forge env up` sets on a frontend's dev server
+ * when the frontend's runtime config document was rendered outside its tree.
+ * Its value is an absolute path.
+ */
+export declare const FORGE_RUNTIME_CONFIG_FILE_ENV = "FORGE_RUNTIME_CONFIG_FILE";
+type NextFn = (err?: unknown) => void;
+type Middleware = (req: IncomingMessage, res: ServerResponse, next: NextFn) => void;
+/** The part of a Vite dev / preview server this plugin uses. */
+export interface RuntimeConfigServer {
+    config: {
+        base: string;
+        logger: {
+            warn(msg: string): void;
+        };
+    };
+    middlewares: {
+        use(fn: Middleware): unknown;
+    };
+    watcher?: {
+        add(paths: string | readonly string[]): unknown;
+        on(event: "change", listener: (path: string) => void): unknown;
+    };
+    ws?: {
+        send(payload: {
+            type: "full-reload";
+            path?: string;
+        }): void;
+    };
+}
+export interface ForgeRuntimeConfigOptions {
+    /**
+     * The document to serve. Defaults to `process.env.FORGE_RUNTIME_CONFIG_FILE`
+     * as the dev server sees it. Empty or unset makes the plugin inert.
+     */
+    file?: string;
+}
+/** The plugin object; structurally a Vite `Plugin`. */
+export interface ForgeRuntimeConfigPlugin {
+    name: string;
+    configureServer(server: RuntimeConfigServer): void;
+    configurePreviewServer(server: RuntimeConfigServer): void;
+}
+/**
+ * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered
+ * for this frontend, when there is one. Add it to `plugins` in
+ * vite.config.ts:
+ *
+ * ```ts
+ * import { forgeRuntimeConfig } from "@reliantlabs/forge-web-runtime/vite";
+ * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });
+ * ```
+ */
+export declare function forgeRuntimeConfig(options?: ForgeRuntimeConfigOptions): ForgeRuntimeConfigPlugin;
+export {};

package/dist/vite.js

@@ -0,0 +1,116 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// forgeRuntimeConfig — a Vite plugin that serves the frontend's runtime
+// config document (`config.js`, which sets `window.__FORGE_CONFIG__`) from a
+// file forge rendered OUTSIDE the frontend's own tree.
+//
+// # Why
+//
+// A frontend normally carries its dev document at `public/config.js`, written
+// by `forge generate` / `forge env up` in the project that owns the frontend.
+// A frontend whose code lives in ANOTHER repository — a sibling checkout
+// (`path: "../reliant/web"`) in dev, a source pin when building — has no
+// directory forge may write into: putting one repo's rendered environment in
+// another repo's working tree is a diff in someone else's `git status`. So the
+// project that declares the environment renders the document to its own
+// `.forge/runtime-config/<frontend>/config.js`, and `forge env up` hands the
+// path to the frontend's dev server as FORGE_RUNTIME_CONFIG_FILE. This plugin
+// is the dev server's half: it answers `<base>config.js` from that file.
+//
+// With the variable unset (the frontend's own repo runs its own dev server,
+// or a build) the plugin does nothing, and `public/config.js` is served as
+// before — so adding it to a vite.config.ts is safe in every mode.
+//
+// The file is read on EVERY request rather than once: `forge env up`
+// re-renders it after identity and jobs converge, and a page reload must see
+// that, not the value from when the dev server started. A change also sends
+// the page a full reload, so an open tab picks it up without a click.
+//
+// Structural types only: this module imports nothing from `vite`, so the
+// package takes no dependency on any Vite major. The plugin object is
+// assignable to Vite's `Plugin` (vite.test.ts pins that).
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+/**
+ * The environment variable `forge env up` sets on a frontend's dev server
+ * when the frontend's runtime config document was rendered outside its tree.
+ * Its value is an absolute path.
+ */
+export const FORGE_RUNTIME_CONFIG_FILE_ENV = "FORGE_RUNTIME_CONFIG_FILE";
+/** The document's file name, which is also the path it is served at. */
+const CONFIG_JS = "config.js";
+/**
+ * configPath is the request path the document is served at under `base`.
+ * Vite normalizes a dev server's base to "/" or "/prefix/"; a relative base
+ * ("./", a build-only setting) is served from the root.
+ */
+function configPath(base) {
+    const b = base.startsWith("/") ? base : "/";
+    return (b.endsWith("/") ? b : `${b}/`) + CONFIG_JS;
+}
+function requestPath(req) {
+    const url = req.url ?? "";
+    const q = url.search(/[?#]/);
+    return q < 0 ? url : url.slice(0, q);
+}
+/**
+ * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered
+ * for this frontend, when there is one. Add it to `plugins` in
+ * vite.config.ts:
+ *
+ * ```ts
+ * import { forgeRuntimeConfig } from "@reliantlabs/forge-web-runtime/vite";
+ * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });
+ * ```
+ */
+export function forgeRuntimeConfig(options = {}) {
+    const raw = options.file ?? process.env[FORGE_RUNTIME_CONFIG_FILE_ENV] ?? "";
+    const file = raw.trim() === "" ? "" : resolve(raw.trim());
+    const install = (server, live) => {
+        if (file === "")
+            return;
+        const path = configPath(server.config.base);
+        server.middlewares.use((req, res, next) => {
+            if ((req.method !== "GET" && req.method !== "HEAD") ||
+                requestPath(req) !== path) {
+                next();
+                return;
+            }
+            readFile(file, "utf8").then((body) => {
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+                // The document is per environment and re-rendered while the dev
+                // server runs; a cached copy is a stale environment.
+                res.setHeader("Cache-Control", "no-store");
+                res.end(req.method === "HEAD" ? undefined : body);
+            }, (err) => {
+                // Loud, not silent: the page will fall back to whatever
+                // public/config.js says (or to config_gen.ts's defaults), and the
+                // only clue is this line in the dev server's log.
+                server.config.logger.warn(`[forge-runtime-config] ${FORGE_RUNTIME_CONFIG_FILE_ENV}=${file} is unreadable ` +
+                    `(${err instanceof Error ? err.message : String(err)}); ` +
+                    `serving ${path} from the frontend's own tree instead. ` +
+                    "Re-run `forge env up` in the project that declares this frontend.");
+                next();
+            });
+        });
+        if (live && server.watcher) {
+            server.watcher.add(file);
+            server.watcher.on("change", (changed) => {
+                if (resolve(changed) === file) {
+                    server.ws?.send({ type: "full-reload", path: "*" });
+                }
+            });
+        }
+    };
+    return {
+        name: "forge-runtime-config",
+        configureServer(server) {
+            install(server, true);
+        },
+        configurePreviewServer(server) {
+            install(server, false);
+        },
+    };
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// forgeRuntimeConfig — a Vite plugin that serves the frontend's runtime\n// config document (`config.js`, which sets `window.__FORGE_CONFIG__`) from a\n// file forge rendered OUTSIDE the frontend's own tree.\n//\n// # Why\n//\n// A frontend normally carries its dev document at `public/config.js`, written\n// by `forge generate` / `forge env up` in the project that owns the frontend.\n// A frontend whose code lives in ANOTHER repository — a sibling checkout\n// (`path: \"../reliant/web\"`) in dev, a source pin when building — has no\n// directory forge may write into: putting one repo's rendered environment in\n// another repo's working tree is a diff in someone else's `git status`. So the\n// project that declares the environment renders the document to its own\n// `.forge/runtime-config/<frontend>/config.js`, and `forge env up` hands the\n// path to the frontend's dev server as FORGE_RUNTIME_CONFIG_FILE. This plugin\n// is the dev server's half: it answers `<base>config.js` from that file.\n//\n// With the variable unset (the frontend's own repo runs its own dev server,\n// or a build) the plugin does nothing, and `public/config.js` is served as\n// before — so adding it to a vite.config.ts is safe in every mode.\n//\n// The file is read on EVERY request rather than once: `forge env up`\n// re-renders it after identity and jobs converge, and a page reload must see\n// that, not the value from when the dev server started. A change also sends\n// the page a full reload, so an open tab picks it up without a click.\n//\n// Structural types only: this module imports nothing from `vite`, so the\n// package takes no dependency on any Vite major. The plugin object is\n// assignable to Vite's `Plugin` (vite.test.ts pins that).\nimport { readFile } from \"node:fs/promises\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { resolve } from \"node:path\";\n\n/**\n * The environment variable `forge env up` sets on a frontend's dev server\n * when the frontend's runtime config document was rendered outside its tree.\n * Its value is an absolute path.\n */\nexport const FORGE_RUNTIME_CONFIG_FILE_ENV = \"FORGE_RUNTIME_CONFIG_FILE\";\n\n/** The document's file name, which is also the path it is served at. */\nconst CONFIG_JS = \"config.js\";\n\ntype NextFn = (err?: unknown) => void;\ntype Middleware = (\n  req: IncomingMessage,\n  res: ServerResponse,\n  next: NextFn,\n) => void;\n\n/** The part of a Vite dev / preview server this plugin uses. */\nexport interface RuntimeConfigServer {\n  config: {\n    base: string;\n    logger: { warn(msg: string): void };\n  };\n  middlewares: { use(fn: Middleware): unknown };\n  watcher?: {\n    add(paths: string | readonly string[]): unknown;\n    on(event: \"change\", listener: (path: string) => void): unknown;\n  };\n  ws?: { send(payload: { type: \"full-reload\"; path?: string }): void };\n}\n\nexport interface ForgeRuntimeConfigOptions {\n  /**\n   * The document to serve. Defaults to `process.env.FORGE_RUNTIME_CONFIG_FILE`\n   * as the dev server sees it. Empty or unset makes the plugin inert.\n   */\n  file?: string;\n}\n\n/** The plugin object; structurally a Vite `Plugin`. */\nexport interface ForgeRuntimeConfigPlugin {\n  name: string;\n  configureServer(server: RuntimeConfigServer): void;\n  configurePreviewServer(server: RuntimeConfigServer): void;\n}\n\n/**\n * configPath is the request path the document is served at under `base`.\n * Vite normalizes a dev server's base to \"/\" or \"/prefix/\"; a relative base\n * (\"./\", a build-only setting) is served from the root.\n */\nfunction configPath(base: string): string {\n  const b = base.startsWith(\"/\") ? base : \"/\";\n  return (b.endsWith(\"/\") ? b : `${b}/`) + CONFIG_JS;\n}\n\nfunction requestPath(req: IncomingMessage): string {\n  const url = req.url ?? \"\";\n  const q = url.search(/[?#]/);\n  return q < 0 ? url : url.slice(0, q);\n}\n\n/**\n * forgeRuntimeConfig serves `<base>config.js` from the file forge rendered\n * for this frontend, when there is one. Add it to `plugins` in\n * vite.config.ts:\n *\n * ```ts\n * import { forgeRuntimeConfig } from \"@reliantlabs/forge-web-runtime/vite\";\n * export default defineConfig({ plugins: [react(), forgeRuntimeConfig()] });\n * ```\n */\nexport function forgeRuntimeConfig(\n  options: ForgeRuntimeConfigOptions = {},\n): ForgeRuntimeConfigPlugin {\n  const raw = options.file ?? process.env[FORGE_RUNTIME_CONFIG_FILE_ENV] ?? \"\";\n  const file = raw.trim() === \"\" ? \"\" : resolve(raw.trim());\n\n  const install = (server: RuntimeConfigServer, live: boolean): void => {\n    if (file === \"\") return;\n    const path = configPath(server.config.base);\n    server.middlewares.use((req, res, next) => {\n      if (\n        (req.method !== \"GET\" && req.method !== \"HEAD\") ||\n        requestPath(req) !== path\n      ) {\n        next();\n        return;\n      }\n      readFile(file, \"utf8\").then(\n        (body) => {\n          res.statusCode = 200;\n          res.setHeader(\"Content-Type\", \"text/javascript; charset=utf-8\");\n          // The document is per environment and re-rendered while the dev\n          // server runs; a cached copy is a stale environment.\n          res.setHeader(\"Cache-Control\", \"no-store\");\n          res.end(req.method === \"HEAD\" ? undefined : body);\n        },\n        (err: unknown) => {\n          // Loud, not silent: the page will fall back to whatever\n          // public/config.js says (or to config_gen.ts's defaults), and the\n          // only clue is this line in the dev server's log.\n          server.config.logger.warn(\n            `[forge-runtime-config] ${FORGE_RUNTIME_CONFIG_FILE_ENV}=${file} is unreadable ` +\n              `(${err instanceof Error ? err.message : String(err)}); ` +\n              `serving ${path} from the frontend's own tree instead. ` +\n              \"Re-run `forge env up` in the project that declares this frontend.\",\n          );\n          next();\n        },\n      );\n    });\n    if (live && server.watcher) {\n      server.watcher.add(file);\n      server.watcher.on(\"change\", (changed) => {\n        if (resolve(changed) === file) {\n          server.ws?.send({ type: \"full-reload\", path: \"*\" });\n        }\n      });\n    }\n  };\n\n  return {\n    name: \"forge-runtime-config\",\n    configureServer(server) {\n      install(server, true);\n    },\n    configurePreviewServer(server) {\n      install(server, false);\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reliantlabs/forge-web-runtime",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and the HyperDX browser SDK wiring (errors, console, network, traces; replay off by default). The web twin of forge/pkg.",
   "license": "Apache-2.0",
   "//repository note": "REQUIRED for `npm publish --provenance`, not decoration. npm cross-checks this against the repository in the signed provenance statement and rejects the publish with a 422 if they disagree — an absent field reads as \"\" and fails that comparison. `directory` names the subdirectory this package lives in, so the provenance points at the real source. Omitting this is what made the first 0.3.1 publish fail AFTER the tarball had been signed and written to the sigstore transparency log.",
@@ -54,6 +54,10 @@
       "types": "./dist/telemetry.d.ts",
       "default": "./dist/telemetry.js"
     },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {