@commercebuild/extension 0.0.14 → 0.0.15

package/config/host-libs.json

@@ -0,0 +1,20 @@
+{
+  "//": "AUTO-GENERATED from packages/extension-host-libs — do not edit. Regenerate with `yarn generate-extension-host-types`.",
+  "external": [
+    "react",
+    "react-dom",
+    "react-dom/client",
+    "firebase/app",
+    "firebase/firestore"
+  ],
+  "globals": {
+    "react": "cb.lib.React",
+    "react-dom": "cb.lib.ReactDOM",
+    "react-dom/client": "cb.lib.ReactDOM",
+    "firebase/app": "cb.lib.firebase.app",
+    "firebase/firestore": "cb.lib.firebase.firestore"
+  },
+  "forbidden": [
+    "firebase/firestore/lite"
+  ]
+}

package/config/vite.config.mjs

@@ -3,7 +3,7 @@ import ViteHMRNotifierPlugin from "../scripts/vite-plugin-hmr-notifier.mjs";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 // import dts from "vite-plugin-dts";
-// import { fileURLToPath } from "url";
+import { fileURLToPath } from "url";
 import path from "path";
 import { existsSync, readFileSync } from "fs";
 import chalk from "chalk";
@@ -30,8 +30,107 @@ const cbMetaBanner = cbApiVersion
       cbApiVersion,
     )}});}}catch(e){}})();`
   : "";
-// const __filename = fileURLToPath(import.meta.url);
-// const __dirname = dirname(__filename);
+
+// Host-provided libraries (import specifier → cb.* global), generated
+// from the cb-store host-lib registry so this build externalizes
+// exactly what the storefront provides. Regenerated by cb-store's
+// `yarn generate-extension-host-types`; do not edit host-libs.json.
+const hostLibs = JSON.parse(
+  readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "host-libs.json"),
+    "utf8",
+  ),
+);
+
+/**
+ * Emit dist/cb-manifest.json alongside the bundle: the host libs this
+ * build actually externalized (the storefront preloads the lazy ones
+ * BEFORE injecting index.js) plus the app's data-connection
+ * declarations copied from config.json. The manifest travels with the
+ * artifact — versioned by uploadId like index.js itself — so nothing
+ * app-side needs to be written to Firestore, and a store pinned to an
+ * old upload gets exactly that upload's declarations.
+ */
+function cbManifestPlugin() {
+  return {
+    name: "cb-emit-manifest",
+    generateBundle(_options, bundle) {
+      // The chunk's own `imports` lists exactly the modules rollup left
+      // external — the ground truth of what the artifact expects the
+      // host to provide (a resolveId hook can't see them: rollup
+      // matches the `external` option before plugins run).
+      const used = new Set();
+      for (const output of Object.values(bundle)) {
+        if (output.type !== "chunk") continue;
+        for (const spec of [...output.imports, ...output.dynamicImports]) {
+          used.add(spec);
+        }
+      }
+      let connections = [];
+      let declaredHostLibs = [];
+      try {
+        const configPath = path.resolve(process.cwd(), "config.json");
+        if (existsSync(configPath)) {
+          const config = JSON.parse(readFileSync(configPath, "utf8"));
+          if (Array.isArray(config.connections)) {
+            connections = config.connections.filter(
+              (c) => c && typeof c === "object" && typeof c.name === "string",
+            );
+          }
+        }
+        const manifestPath = path.resolve(process.cwd(), "commercebuild.json");
+        if (existsSync(manifestPath)) {
+          const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+          // Optional explicit override for anything the resolve hook
+          // can't see (kept for parity with the editor compiler).
+          if (Array.isArray(manifest.hostLibs)) {
+            declaredHostLibs = manifest.hostLibs.filter(
+              (s) => typeof s === "string",
+            );
+          }
+        }
+      } catch {
+        // A broken config fails the type-check/build on its own terms.
+      }
+      this.emitFile({
+        type: "asset",
+        fileName: "cb-manifest.json",
+        source:
+          JSON.stringify(
+            {
+              cbApiVersion,
+              hostLibs: [...new Set([...used, ...declaredHostLibs])].sort(),
+              connections,
+            },
+            null,
+            2,
+          ) + "\n",
+      });
+    },
+  };
+}
+
+// Packages that must never be bundled OR externalized — each would
+// silently conflict with a host lib at runtime (e.g. firestore lite
+// registers the same 'firestore' component as the full SDK, and
+// whichever loads first wins with no error).
+function forbiddenImportsPlugin() {
+  const forbidden = new Set(hostLibs.forbidden ?? []);
+  return {
+    name: "cb-forbidden-imports",
+    enforce: "pre",
+    resolveId(source) {
+      if (forbidden.has(source)) {
+        throw new Error(
+          `"${source}" cannot be used in a commercebuild extension — ` +
+            `the host provides a conflicting implementation. ` +
+            `Import the host-provided module instead (see host-libs.json).`,
+        );
+      }
+      return null;
+    },
+  };
+}
 
 const jsEntry = path.resolve(process.cwd(), "src/index.js");
 const tsEntry = path.resolve(process.cwd(), "src/index.ts");
@@ -48,13 +147,10 @@ const baseBuildConfig = {
   minify: "esbuild",
   sourcemap: false,
   rollupOptions: {
-    external: ["react", "react-dom"],
+    external: hostLibs.external,
     output: {
       banner: cbMetaBanner,
-      globals: {
-        react: "cb.lib.React",
-        "react-dom": "cb.lib.ReactDom",
-      },
+      globals: hostLibs.globals,
       assetFileNames: (assetInfo) => {
         if (assetInfo.name.endsWith(".css")) {
           return assetInfo.originalFileName || assetInfo.name || "asset.css";
@@ -67,6 +163,8 @@ const baseBuildConfig = {
 
 const prodConfig = {
   plugins: [
+    forbiddenImportsPlugin(),
+    cbManifestPlugin(),
     react({
       jsxRuntime: "classic",
     }),
@@ -106,6 +204,8 @@ export default defineConfig(({ mode, command }) => {
     return {
       root: ".",
       plugins: [
+        forbiddenImportsPlugin(),
+        cbManifestPlugin(),
         ViteHMRNotifierPlugin(),
         react({
           jsxRuntime: "classic",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercebuild/extension",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
@@ -22,6 +22,7 @@
     "@vitejs/plugin-react": "^4.5.2",
     "chalk": "^5.4.1",
     "esbuild": "^0.25.6",
+    "firebase": "^12.2.1",
     "lucide-react": "^0.525.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -34,4 +35,4 @@
   "bin": {
     "commercebuild-extension": "./scripts/cli.js"
   }
-}
+}

package/schemas/config.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "commercebuild extension configuration",
+  "description": "Data-connection declarations (config.json) or development overrides (config.development.json — never deployed, matched to declarations by name).",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "connections": {
+      "type": "array",
+      "description": "Named data connections. In config.json each entry declares a connection; in config.development.json each entry overrides the declaration with the same name (scratch names may be introduced for testing).",
+      "items": {
+        "$ref": "#/$defs/connection"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "connection": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_-]*$",
+          "description": "Connection name the app code passes to cb.utils.useFirebaseApp(name). With exactly one connection configured, useFirebaseApp() with no argument resolves it; otherwise the no-argument form looks for \"default\"."
+        },
+        "provider": {
+          "description": "Backing service. Absent means \"firebase\".",
+          "enum": [
+            "firebase"
+          ]
+        },
+        "scope": {
+          "description": "\"store\" (the default): the merchant supplies the config per store under Installed Apps → Configure data — do not put a config here. \"app\": the config is fixed in this declaration (required below), owned by the app and not merchant-overridable.",
+          "enum": [
+            "store",
+            "app"
+          ],
+          "default": "store"
+        },
+        "label": {
+          "type": "string",
+          "description": "Shown as the connection's title in the merchant's config form."
+        },
+        "description": {
+          "type": "string",
+          "description": "Shown under the label in the merchant's config form."
+        },
+        "config": {
+          "$ref": "#/$defs/firebaseConfig"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "scope": {
+                "const": "app"
+              }
+            },
+            "required": [
+              "scope"
+            ]
+          },
+          "then": {
+            "required": [
+              "config"
+            ]
+          }
+        }
+      ]
+    },
+    "firebaseConfig": {
+      "type": "object",
+      "description": "Firebase web config (the firebaseConfig snippet from the Firebase console). Public by design — access control lives in the project's Security Rules.",
+      "required": [
+        "apiKey",
+        "projectId"
+      ],
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "minLength": 1
+        },
+        "projectId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "authDomain": {
+          "type": "string"
+        },
+        "storageBucket": {
+          "type": "string"
+        },
+        "messagingSenderId": {
+          "type": "string"
+        },
+        "appId": {
+          "type": "string"
+        },
+        "measurementId": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/types/global.d.ts

@@ -6,6 +6,8 @@
 import * as React from "react";
 import React__default, { CSSProperties } from "react";
 import * as ReactDOM from "react-dom";
+import * as FirebaseAppNs from "firebase/app";
+import * as FirebaseFirestoreNs from "firebase/firestore";
 import { cart_v2, catalog_v1, Platform } from "@commercebuild/platform-api";
 import * as icons from "lucide-react";
 import * as uis from "@commercebuild/ui";
@@ -283,6 +285,37 @@ declare function revalidatePath(
 ): Promise<void>;
 declare function revalidate(): Promise<void>;
 
+/**
+ * Per-extension render scope.
+ *
+ * Extension code has no runtime identity of its own — components are
+ * bare functions and `cb` is one page-global object, while a single
+ * React tree can hold components from several different extensions at
+ * once. This context supplies that identity lexically: the host wraps
+ * every extension render site (renderExtensionComponent's boundary and
+ * the extension page route) in a provider carrying the registration id
+ * and the extension's resolved per-store configuration. Contract hooks
+ * like cb.utils.useFirebaseApp() read it, so the same component gets
+ * its own extension's connections wherever it renders — including the
+ * synthetic "preview" / "local" registrations, which just carry their
+ * own scope value.
+ */
+
+/**
+ * Merchant-supplied Firebase web config (the Firebase-console snippet
+ * subset). Not a secret — it ships to every browser by design; access
+ * control lives entirely in the merchant's Firestore Security Rules.
+ */
+interface CbFirebaseConfig {
+  apiKey: string;
+  projectId: string;
+  authDomain?: string;
+  storageBucket?: string;
+  messagingSenderId?: string;
+  appId?: string;
+  measurementId?: string;
+}
+
 /**
  * The extension host API contract (`window.cb`).
  *
@@ -427,6 +460,17 @@ type CbImage = React.ForwardRefExoticComponent<
     lazyRoot?: string;
   } & React.RefAttributes<HTMLImageElement | null>
 >;
+
+/**
+ * Import specifier → module namespace for every runtime host lib, so
+ * `cb.requireLib("firebase/firestore")` returns the fully typed module.
+ */
+interface CbHostLibs {
+  react: typeof React;
+  "react-dom": typeof ReactDOM;
+  "firebase/app": typeof FirebaseAppNs;
+  "firebase/firestore": typeof FirebaseFirestoreNs;
+}
 interface CbHostApi {
   /** Host-contract semver — see docs/extension-host-api/versioning.md. */
   version: string;
@@ -435,12 +479,28 @@ interface CbHostApi {
    * shares the host's single instance instead of bundling its own (critical for
    * React — two instances break hooks). The extension build maps
    * `import ... from "react"` → `cb.lib.React` and `"react-dom"` →
-   * `cb.lib.ReactDom`.
+   * `cb.lib.ReactDOM`.
    */
   lib: {
     React: typeof React;
-    ReactDom: typeof ReactDOM;
+    ReactDOM: typeof ReactDOM;
+    /**
+     * Lazy host libs, bound by the extension build — do not read
+     * directly. The host import()s each one before injecting a bundle
+     * that declared it; until then a member read throws a descriptive
+     * error naming the missing lib. Use `cb.requireLib(...)` for an
+     * explicit, typed lookup.
+     */
+    firebase: {
+      app: typeof FirebaseAppNs;
+      firestore: typeof FirebaseFirestoreNs;
+    };
   };
+  /**
+   * The module namespace for a runtime host lib, throwing a descriptive
+   * error when it is not loaded (the extension didn't declare it).
+   */
+  requireLib: <S extends keyof CbHostLibs>(spec: S) => CbHostLibs[S];
   /** The platform (commerce backend) API SDK client. */
   platform: Platform;
   /**
@@ -459,6 +519,23 @@ interface CbHostApi {
     revalidate: typeof revalidate;
     revalidateTag: typeof revalidateTag;
     revalidatePath: typeof revalidatePath;
+    /**
+     * React hook: connection names the store configured for the current
+     * extension (via storeadmin → Installed Apps → Configure data).
+     * Empty outside an extension subtree.
+     */
+    useFirebaseConnections: () => string[];
+    /**
+     * React hook: the host-initialized FirebaseApp for a named
+     * connection, or undefined when it is not configured — always
+     * render a fallback for that case. With no argument: the store's
+     * only connection when exactly one is configured, else the one
+     * named "default". Never call initializeApp yourself; pass this app
+     * to the product entry points (e.g. getFirestore(app)).
+     */
+    useFirebaseApp: (
+      connection?: string,
+    ) => FirebaseAppNs.FirebaseApp | undefined;
   };
   com: {
     Cart: {
@@ -521,4 +598,4 @@ declare global {
   }
 }
 
-export type { CbHostApi, CbHostDeps, CbRouter };
+export type { CbFirebaseConfig, CbHostApi, CbHostDeps, CbHostLibs, CbRouter };