create-bluecopa-react-app 1.0.42 → 1.0.44

package/templates/latest/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — React MFE Boilerplate
 
-This file provides guidance to Claude Code when working with the Bluecopa React MFE (Micro-Frontend) boilerplate.
+This file provides guidance to Claude Code when working with the Bluecopa React MFE (Micro-Frontend) boilerplate. It is the **single source of truth** for agent guidance — `Agent.md` points here.
 
 ## Project Overview
 
@@ -33,18 +33,48 @@ interface MfeProps {
   accessToken?: string;    // JWT auth token
   userId?: string;         // Current user ID
   basename?: string;       // Router basename
+  envVars?: EnvConfig;     // Runtime env (workbook `storedEnvVariable`) — see below
+  schemaMap?: SchemaMap;   // Column-name normalization (workbook `storedSchemaMap`)
 }
 ```
 
 Props are passed from the host app via single-spa `customProps` or `manualMount()`.
 
+### Runtime config: `envVars` (CRITICAL)
+
+The host injects an `envVars` object built from the app's **Settings → Env Vars** panel
+(persisted on the workbook as `storedEnvVariable`). This is the **only** way to configure a
+deployed app without a rebuild — build-time `import.meta.env` is empty in the federated
+`remoteEntry`. `app.tsx` merges them: `{ ...import.meta.env, ...props.envVars }`, host wins.
+The merged object is exposed via `useAppContext().envConfig`. Add each of your app's keys (table
+IDs, dataset IDs, …) **explicitly** to the `EnvConfig` interface in `app/types/index.ts` for
+type-safe access — prefer this over the index signature, which is only a last-resort fallback for
+keys you haven't typed yet.
+
+### Solution-context headers (Input Table V2)
+
+`copaSetConfig` is applied **synchronously** in `app.tsx` (a `useState` initializer, so the first
+SDK call already carries the right headers) and **re-applied via a `useEffect`** when the host
+pushes new props/env after mount (e.g. a refreshed access token or updated `storedEnvVariable`).
+It sets the `x-bluecopa-solution-*` headers from `envVars.VITE_BLUECOPA_SOLUTION_ID` /
+`_SOLUTION_BRANCH` / `_SOLUTION_BRANCH_TYPE` — **required by the Input Table V2 SDK
+(`copaInputTableDb`)**. Defaults: branch `main`, type `REMOTE`.
+
+### Error handling
+
+`app/components/error-boundary.tsx` (`RouteErrorBoundary`) wraps the routed tree in `app.tsx`.
+Without it, a render-phase throw unmounts the whole MFE and the host shows a blank div. It
+auto-retries once (handles cache-cold races on first mount), then shows a visible error panel
+with dev-only diagnostics.
+
 ### Key Files
 
 | File | Purpose |
 |------|---------|
 | `app/app.tsx` | Root component — QueryClient, ChartProvider, MFE config, AppProvider |
 | `app/app.css` | Tailwind v4 config + Dream Light theme tokens |
-| `app/contexts/app-context.tsx` | User, workspace settings, admin role context |
+| `app/contexts/app-context.tsx` | User, workspace settings, admin role + `envConfig`/`schemaMap` |
+| `app/components/error-boundary.tsx` | `RouteErrorBoundary` — wraps routes, auto-retry-once |
 | `app/routes/index.tsx` | Route definitions (all wrapped in AppLayout) |
 | `app/utils/utils.ts` | `cn()` utility with `copa` prefix support |
 | `app/utils/component-style.ts` | Unprefixed style tokens (source of truth) |
@@ -144,7 +174,7 @@ React Query hooks wrapping `@bluecopa/core`. All data fetching uses these hooks.
 
 ### Setup Flow
 
-1. `copaSetConfig()` called in `app.tsx` useEffect with MFE props or env vars
+1. `copaSetConfig()` called **synchronously** in `app.tsx` (a `useState` initializer) from merged MFE props + env vars, then **re-applied via a `useEffect`** when those props/env change
 2. `QueryClientProvider` wraps the app (staleTime: 5min, retry: 1)
 3. Hooks become available in all child components
 
@@ -166,6 +196,15 @@ copaSetConfig({
 ```bash
 VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
 VITE_BLUECOPA_WORKSPACE_ID=prod
+VITE_BLUECOPA_API_TOKEN=                  # standalone dev only
+VITE_BLUECOPA_USER_ID=
+VITE_AG_GRID_LICENSE_KEY=
+
+# Solution context (Input Table V2). In a DEPLOYED app these arrive via the
+# host's Settings → Env Vars panel (envVars), not this file.
+VITE_BLUECOPA_SOLUTION_ID=
+VITE_BLUECOPA_SOLUTION_BRANCH=main
+VITE_BLUECOPA_SOLUTION_BRANCH_TYPE=REMOTE
 ```
 
 ### Available Hooks
@@ -756,4 +795,4 @@ Use `lucide-react` or `@tabler/icons-react` (both available).
 3. **`.mfe-root` not `:root`**: All CSS variables scoped to `.mfe-root` for MFE isolation
 4. **Breakpoints with prefix**: Must explicitly define `--breakpoint-*` vars in `@theme` (Tailwind v4 doesn't auto-include them with prefix)
 5. **ReactQueryDevtools**: Only rendered in dev mode (`import.meta.env.DEV`)
-6. **Config before queries**: `copaSetConfig()` must complete before React Query hooks fire. The app gates rendering behind `isConfigured` state.
+6. **Config before queries**: `copaSetConfig()` runs synchronously in a `useState` initializer (before any child renders), so the first React Query hook call already has config — no `isConfigured` render gate. It is also re-applied via a `useEffect` when props/env change (e.g. token refresh).

package/templates/latest/app/app.tsx

@@ -1,55 +1,90 @@
 import "./app.css";
-import { useState, useEffect } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { reactQuery, ReactQueryDevtools, copaSetConfig } from "@bluecopa/react";
 import { Toaster } from "~/components/ui/sonner";
 import { AppProvider } from "~/contexts/app-context";
 import { ChartProvider } from "~/components/charts";
-import { LoadingScreen } from "~/components/loading-screen";
+import { RouteErrorBoundary } from "~/components/error-boundary";
 import RouteConfig from "./routes";
-import type { MfeProps } from "~/types";
-import { DEFAULT_API_BASE_URL, DEFAULT_WORKSPACE_ID, QUERY_DEFAULTS } from "~/constants";
+import type { EnvConfig, MfeProps } from "~/types";
+import {
+  DEFAULT_API_BASE_URL,
+  DEFAULT_SOLUTION_BRANCH,
+  DEFAULT_SOLUTION_BRANCH_TYPE,
+  DEFAULT_WORKSPACE_ID,
+  QUERY_DEFAULTS,
+} from "~/constants";
 import { initAgGridLicense } from "~/utils/ag-grid-license";
 
 const { QueryClient, QueryClientProvider } = reactQuery;
 
 export default function App(props: MfeProps) {
-  const [isConfigured, setIsConfigured] = useState(false);
-  const [queryClient] = useState(
+  // Merge runtime env (host `envVars`) over build-time `import.meta.env`. Host
+  // values win so a deployed app can be reconfigured from the Settings → Env
+  // Vars panel without a rebuild. Recomputed if the host re-injects `envVars`.
+  const envConfig = useMemo<EnvConfig>(
     () =>
-      new QueryClient({
-        defaultOptions: {
-          queries: { staleTime: QUERY_DEFAULTS.STALE_TIME, retry: QUERY_DEFAULTS.RETRY },
-        },
-      }),
+      ({ ...import.meta.env, ...(props.envVars ?? {}) }) as unknown as EnvConfig,
+    [props.envVars],
   );
 
-  useEffect(() => {
-    initAgGridLicense();
-    copaSetConfig({
+  // SDK config: top-level mount props win over env. Solution-context headers
+  // (`x-bluecopa-solution-*`) are required by the Input Table V2 SDK and only
+  // ever arrive via the host's `envVars`.
+  const sdkConfig = useMemo(
+    () => ({
       apiBaseUrl:
-        props.apiBaseUrl ||
-        import.meta.env.VITE_BLUECOPA_API_URL ||
-        DEFAULT_API_BASE_URL,
-      accessToken: props.accessToken || "",
+        props.apiBaseUrl || envConfig.VITE_BLUECOPA_API_URL || DEFAULT_API_BASE_URL,
+      accessToken: props.accessToken || envConfig.VITE_BLUECOPA_API_TOKEN || "",
       workspaceId:
         props.workspaceId ||
-        import.meta.env.VITE_BLUECOPA_WORKSPACE_ID ||
+        envConfig.VITE_BLUECOPA_WORKSPACE_ID ||
         DEFAULT_WORKSPACE_ID,
-      userId: props.userId || "",
-    });
-    setIsConfigured(true);
-  }, [props.apiBaseUrl, props.accessToken, props.workspaceId, props.userId]);
+      userId: props.userId || envConfig.VITE_BLUECOPA_USER_ID || "",
+      solutionId: envConfig.VITE_BLUECOPA_SOLUTION_ID || undefined,
+      solutionBranch:
+        envConfig.VITE_BLUECOPA_SOLUTION_BRANCH || DEFAULT_SOLUTION_BRANCH,
+      solutionBranchType:
+        envConfig.VITE_BLUECOPA_SOLUTION_BRANCH_TYPE ||
+        DEFAULT_SOLUTION_BRANCH_TYPE,
+    }),
+    [props.apiBaseUrl, props.accessToken, props.workspaceId, props.userId, envConfig],
+  );
 
-  if (!isConfigured) {
-    return <LoadingScreen message="Initializing..." />;
-  }
+  // Configure the SDK SYNCHRONOUSLY before any child renders, so hooks that read
+  // userId/solutionId from the SDK on their first call (useUser, Input Table V2)
+  // see the right values — a useEffect alone would render children once with
+  // empty config. This initializer runs exactly once on mount.
+  useState(() => {
+    copaSetConfig(sdkConfig);
+    initAgGridLicense(envConfig.VITE_AG_GRID_LICENSE_KEY);
+    return null;
+  });
+
+  // Re-apply when the host pushes new props/env after mount (e.g. a refreshed
+  // access token or updated solution headers). `copaSetConfig` shallow-merges
+  // into a singleton, so re-applying is idempotent.
+  useEffect(() => {
+    copaSetConfig(sdkConfig);
+  }, [sdkConfig]);
+
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: { staleTime: QUERY_DEFAULTS.STALE_TIME, retry: QUERY_DEFAULTS.RETRY },
+        },
+      }),
+  );
 
   return (
     <QueryClientProvider client={queryClient}>
       <div className="mfe-root copa:min-h-svh copa:animate-in copa:fade-in copa:duration-300">
         <ChartProvider>
-          <AppProvider>
-            <RouteConfig />
+          <AppProvider envConfig={envConfig} schemaMap={props.schemaMap}>
+            <RouteErrorBoundary>
+              <RouteConfig />
+            </RouteErrorBoundary>
             <Toaster />
           </AppProvider>
         </ChartProvider>

package/templates/latest/app/components/error-boundary.tsx

@@ -0,0 +1,178 @@
+import {
+  Component,
+  Fragment,
+  type ErrorInfo,
+  type ReactNode,
+} from "react";
+
+interface Props {
+  children: ReactNode;
+}
+
+interface State {
+  error: Error | null;
+  info: ErrorInfo | null;
+  /** Number of times we've remounted children after a caught error. Used as a
+   *  React `key` on the children fragment so a bumped count forces a fresh
+   *  unmount/remount instead of a re-render. */
+  retryKey: number;
+  /** Whether the auto-retry slot has been consumed. We auto-retry exactly once
+   *  per boundary lifetime (until a manual reset via "Try again"), then surface
+   *  the error UI on a second consecutive throw so we don't loop forever. */
+  autoRetryUsed: boolean;
+}
+
+const AUTO_RETRY_DELAY_MS = 100;
+
+/**
+ * Route-level error boundary. Without this, a render-phase throw anywhere
+ * inside the routed tree unmounts the whole MFE and the single-spa host
+ * renders a blank div — the classic "white screen, no console error" symptom.
+ *
+ * The boundary auto-retries once on the first error. This catches the common
+ * "cache-cold race on initial mount" pattern: the first mount throws because a
+ * dependent dataset is still empty, but that failed mount triggered the fetch
+ * that warms the cache, so the remount succeeds against populated data. The
+ * 100ms delay lets any in-flight `setState` from the failed mount flush and
+ * the dependent fetches start resolving. If the retry also fails, we stop and
+ * show the visible error panel instead of looping forever.
+ */
+export class RouteErrorBoundary extends Component<Props, State> {
+  state: State = {
+    error: null,
+    info: null,
+    retryKey: 0,
+    autoRetryUsed: false,
+  };
+
+  private retryTimer: number | null = null;
+
+  static getDerivedStateFromError(error: Error): Partial<State> {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    // Prefix is intentional — makes the error easy to spot in the host console
+    // where other MFEs may also be logging.
+    console.error("[ROUTE BOUNDARY]", error, info);
+    this.setState({ info });
+
+    if (this.state.autoRetryUsed) {
+      // Already auto-retried once — don't loop. The user will see the visible
+      // error panel below (and can still reset manually via "Try again").
+      return;
+    }
+
+    // Schedule the remount on a macrotask so React finishes commit on the
+    // failed mount before we clear the error and bump the key. A synchronous
+    // setState here would be coalesced into the same batch as the error-derived
+    // state update and the unmount/remount cycle wouldn't happen.
+    this.retryTimer = window.setTimeout(() => {
+      this.retryTimer = null;
+      this.setState((s) => ({
+        error: null,
+        info: null,
+        retryKey: s.retryKey + 1,
+        autoRetryUsed: true,
+      }));
+    }, AUTO_RETRY_DELAY_MS);
+  }
+
+  componentWillUnmount(): void {
+    if (this.retryTimer !== null) {
+      window.clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+  }
+
+  handleReset = (): void => {
+    this.setState((s) => ({
+      error: null,
+      info: null,
+      retryKey: s.retryKey + 1,
+      autoRetryUsed: false,
+    }));
+  };
+
+  render(): ReactNode {
+    if (this.state.error) {
+      const message = this.state.error.message || String(this.state.error);
+      const stack = this.state.error.stack ?? "";
+      const componentStack = this.state.info?.componentStack ?? "";
+      // Stack + component stack are leaky in prod (file paths, internal symbol
+      // names) and aren't useful to end users — show them in dev only. The full
+      // error is still logged via `componentDidCatch` for any deploy.
+      const showDiagnostics = import.meta.env.DEV;
+
+      return (
+        <div className="copa:flex copa:min-h-svh copa:items-start copa:justify-center copa:bg-background copa:p-6">
+          <div className="copa:w-full copa:max-w-3xl copa:space-y-4">
+            <div>
+              <h1 className="copa:text-xl copa:font-semibold copa:text-foreground">
+                Something went wrong on this page
+              </h1>
+              <p className="copa:mt-1 copa:text-sm copa:text-muted-foreground">
+                The page errored while rendering. Details are below — share this
+                with engineering if it keeps happening.
+              </p>
+            </div>
+            <div className="copa:rounded-md copa:border copa:border-destructive/40 copa:bg-destructive/5 copa:p-4">
+              <p className="copa:text-sm copa:font-medium copa:text-destructive">
+                {message}
+              </p>
+            </div>
+            {showDiagnostics && (
+              <details className="copa:rounded-md copa:border copa:bg-muted/30 copa:p-4 copa:text-xs">
+                <summary className="copa:cursor-pointer copa:text-sm copa:font-medium">
+                  Stack trace
+                </summary>
+                <pre className="copa:mt-2 copa:overflow-auto copa:whitespace-pre-wrap">
+                  {stack}
+                </pre>
+              </details>
+            )}
+            {showDiagnostics && componentStack && (
+              <details className="copa:rounded-md copa:border copa:bg-muted/30 copa:p-4 copa:text-xs">
+                <summary className="copa:cursor-pointer copa:text-sm copa:font-medium">
+                  Component stack
+                </summary>
+                <pre className="copa:mt-2 copa:overflow-auto copa:whitespace-pre-wrap">
+                  {componentStack}
+                </pre>
+              </details>
+            )}
+            <div className="copa:flex copa:gap-2">
+              <button
+                type="button"
+                onClick={this.handleReset}
+                className="copa:inline-flex copa:items-center copa:rounded-md copa:border copa:border-input copa:bg-background copa:px-4 copa:py-2 copa:text-sm copa:font-medium copa:hover:bg-accent"
+              >
+                Try again
+              </button>
+              <button
+                type="button"
+                onClick={() => {
+                  // Full reload of the CURRENT url — preserves the host-provided
+                  // MFE basename. Navigating to "/" would escape the mounted app
+                  // to the host root.
+                  window.location.reload();
+                }}
+                className="copa:inline-flex copa:items-center copa:rounded-md copa:bg-primary copa:px-4 copa:py-2 copa:text-sm copa:font-medium copa:text-primary-foreground copa:hover:bg-primary/90"
+              >
+                Reload page
+              </button>
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    // `key` is the lynchpin of the auto-retry: bumping it on retry causes React
+    // to fully unmount the old subtree and mount a fresh one, resetting every
+    // hook's local state. Without the key, React would re-render in place with
+    // the same hook state that just threw, and we'd loop on the same error.
+    return (
+      <Fragment key={this.state.retryKey}>{this.props.children}</Fragment>
+    );
+  }
+}

package/templates/latest/app/constants/index.ts

@@ -11,6 +11,13 @@ export const ROUTES = {
 export const DEFAULT_API_BASE_URL = "http://localhost:3000/api/v1";
 export const DEFAULT_WORKSPACE_ID = "prod";
 
+// ─── Solution Context Defaults ──────────────────────────────────────────────
+// Used for the `x-bluecopa-solution-*` SDK headers (Input Table V2 / deployed
+// solutions). There is no guaranteed branch named `local` — the default branch
+// on a solution is `main`/`REMOTE`.
+export const DEFAULT_SOLUTION_BRANCH = "main";
+export const DEFAULT_SOLUTION_BRANCH_TYPE = "REMOTE";
+
 /** React Query defaults */
 export const QUERY_DEFAULTS = {
   STALE_TIME: 5 * 60 * 1000, // 5 minutes

package/templates/latest/app/contexts/app-context.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, useMemo, useState, type ReactNode } from "react";
 import { useUser, useGetAllUsers } from "@bluecopa/react";
-import type { AppUser, WorkspaceDataSettings } from "~/types";
+import type { AppUser, EnvConfig, SchemaMap, WorkspaceDataSettings } from "~/types";
 import { DEFAULT_WORKSPACE_SETTINGS } from "~/constants";
 
 interface AppContextValue {
@@ -17,6 +17,10 @@ interface AppContextValue {
   /** Workspace data settings (currency, timezone, date format, fiscal year, number settings, week start day) */
   currentWorkspaceSettings: WorkspaceDataSettings;
   setCurrency: (currency: string) => void;
+  /** Merged runtime env config (host `envVars` over build-time `import.meta.env`). */
+  envConfig: EnvConfig;
+  /** Column-name normalization map injected by the host (workbook `storedSchemaMap`). */
+  schemaMap: SchemaMap;
 }
 
 const AppContext = createContext<AppContextValue | undefined>(undefined);
@@ -65,9 +69,19 @@ function getWorkspaceDataSettings(workspace: unknown): WorkspaceDataSettings {
 
 export type AppProviderProps = {
   children: ReactNode;
+  /** Merged runtime env config. Defaults to build-time `import.meta.env`. */
+  envConfig?: EnvConfig;
+  /** Host-injected schema map. Defaults to empty. */
+  schemaMap?: SchemaMap;
 };
 
-export function AppProvider({ children }: AppProviderProps) {
+/** Stable empty fallback so the context-value memo isn't invalidated every render. */
+const EMPTY_SCHEMA_MAP: SchemaMap = {};
+
+export function AppProvider({ children, envConfig, schemaMap }: AppProviderProps) {
+  const resolvedEnvConfig = (envConfig ??
+    (import.meta.env as unknown as EnvConfig)) as EnvConfig;
+  const resolvedSchemaMap = schemaMap ?? EMPTY_SCHEMA_MAP;
   const [currencyOverride, setCurrencyOverride] = useState<string | null>(null);
 
   const {
@@ -169,6 +183,8 @@ export function AppProvider({ children }: AppProviderProps) {
       usersError: usersError ?? null,
       currentWorkspaceSettings,
       setCurrency: setCurrencyOverride,
+      envConfig: resolvedEnvConfig,
+      schemaMap: resolvedSchemaMap,
     }),
     [
       userWithDetails,
@@ -184,6 +200,8 @@ export function AppProvider({ children }: AppProviderProps) {
       usersLoading,
       usersError,
       currentWorkspaceSettings,
+      resolvedEnvConfig,
+      resolvedSchemaMap,
     ]
   );
 

package/templates/latest/app/single-spa.tsx

@@ -65,6 +65,11 @@ export async function mount(props: MountProps): Promise<void> {
           workspaceId: props.workspaceId,
           apiBaseUrl: props.apiBaseUrl,
           userId: props.userId,
+          // Runtime config + schema map injected by the host. Forwarding these
+          // is what lets a deployed app read its Settings → Env Vars config and
+          // normalize API column names at runtime.
+          envVars: props.envVars,
+          schemaMap: props.schemaMap,
         }}
       />,
     );

package/templates/latest/app/types/index.ts

@@ -1,3 +1,28 @@
+/** Column-name normalization map injected by the host (workbook `storedSchemaMap`).
+ *  Keyed by env-var name → { backendColumn: frontendColumn }. */
+export type SchemaMap = Record<string, Record<string, string>>;
+
+/**
+ * Runtime environment config. The host injects these via the `envVars` prop
+ * (the app's Settings → Env Vars panel, persisted on the workbook). At
+ * build-time / standalone dev they come from `import.meta.env`. The index
+ * signature lets app-specific vars (table IDs, dataset IDs, …) flow through
+ * without being listed here.
+ */
+export interface EnvConfig {
+  VITE_BLUECOPA_API_URL?: string;
+  VITE_BLUECOPA_WORKSPACE_ID?: string;
+  VITE_BLUECOPA_API_TOKEN?: string;
+  VITE_BLUECOPA_USER_ID?: string;
+  VITE_AG_GRID_LICENSE_KEY?: string;
+  /** Required by the Input Table V2 SDK (`copaInputTableDb`). Flows through to
+   *  the `x-bluecopa-solution-*` request headers. */
+  VITE_BLUECOPA_SOLUTION_ID?: string;
+  VITE_BLUECOPA_SOLUTION_BRANCH?: string;
+  VITE_BLUECOPA_SOLUTION_BRANCH_TYPE?: string;
+  [key: string]: string | undefined;
+}
+
 /** Props passed to the MFE root component from the host app (single-spa customProps or manualMount). */
 export interface MfeProps {
   apiBaseUrl?: string;
@@ -5,6 +30,10 @@ export interface MfeProps {
   accessToken?: string;
   userId?: string;
   basename?: string;
+  /** Runtime env vars injected by the host (workbook `storedEnvVariable`). */
+  envVars?: EnvConfig;
+  /** Column-name normalization map injected by the host (workbook `storedSchemaMap`). */
+  schemaMap?: SchemaMap;
 }
 
 /** Normalized user object provided by AppContext. */

package/templates/latest/app/utils/ag-grid-license.ts

@@ -1,7 +1,13 @@
 import { LicenseManager } from "ag-grid-enterprise";
 
-export function initAgGridLicense() {
-  const key = import.meta.env.VITE_AG_GRID_LICENSE_KEY;
+/**
+ * Set the AG Grid Enterprise license key. Pass the key explicitly (e.g. from
+ * the host-injected runtime env config) so a deployed MFE can be licensed from
+ * the Settings → Env Vars panel. Falls back to the build-time env var for
+ * standalone dev.
+ */
+export function initAgGridLicense(licenseKey?: string) {
+  const key = licenseKey || import.meta.env.VITE_AG_GRID_LICENSE_KEY;
   if (!key) {
     console.warn(
       "[AG Grid] No license key found (VITE_AG_GRID_LICENSE_KEY). Enterprise features will show watermarks.",