@checkstack/frontend-api 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @checkstack/frontend-api
 
+## 0.3.8
+
+### Patch Changes
+
+- 67158e2: Standardize package metadata, unify AJV versions to 8.18.0, and enforce monorepo architecture rules via updated ESLint configuration. This ensures consistent package discovery and runtime dependency safety across the platform.
+- Updated dependencies [67158e2]
+  - @checkstack/common@0.6.4
+
+## 0.3.7
+
+### Patch Changes
+
+- 0603d39: Fix onboarding flow not appearing on fresh Docker deployments (issue #79)
+
+  The `.env.example` had `BASE_URL` defaulting to `http://localhost:5173`
+  (the Vite dev server port). Users copying this file verbatim for a Docker
+  deployment would get a frontend that silently made all API calls to the
+  wrong origin, causing empty state and extreme sluggishness.
+
+  **Changes:**
+
+  - `.env.example`: Adds clear comments explaining the value must match the
+    container's exposed port.
+  - `frontend-api` (`RuntimeConfigProvider`): Removes the silent fallback when
+    `/api/config` returns an unreachable baseUrl — instead propagates the error
+    so it can be surfaced.
+  - `frontend` (`App.tsx`): Renders an actionable error screen when the backend
+    config cannot be loaded, showing the exact `BASE_URL` fix and the
+    `docker compose` command to recover.
+  - `docs/getting-started/docker.md`: Adds a dedicated troubleshooting section
+    for this exact misconfiguration.
+
 ## 0.3.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/frontend-api",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -12,8 +12,8 @@
     "react": "^18.0.0"
   },
   "dependencies": {
-    "@checkstack/common": "0.6.2",
-    "@orpc/client": "^1.13.2",
+    "@checkstack/common": "0.6.3",
+    "@orpc/client": "^1.13.14",
     "@orpc/react-query": "1.13.4",
     "@orpc/tanstack-query": "^1.13.2",
     "@tanstack/react-query": "^5.64.0"
@@ -24,5 +24,8 @@
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.3",
     "@checkstack/scripts": "0.1.1"
+  },
+  "checkstack": {
+    "type": "tooling"
   }
 }

package/src/runtime-config.tsx

@@ -42,8 +42,34 @@ interface RuntimeConfigProviderProps {
 }
 
 /**
- * Fetches runtime config from backend on mount.
- * All consumers should wait for config to load before rendering.
+ * Safely reads the current page origin without requiring the DOM lib
+ * to be in scope in every consuming package's tsconfig.
+ *
+ * Accesses `location` via `globalThis` cast to avoid the untyped-global
+ * error that appears when non-browser packages (e.g. catalog-common) run
+ * TypeScript against this file and their tsconfig doesn't include "DOM".
+ */
+function getCurrentOrigin(): string | undefined {
+  const g = globalThis as Record<string, unknown>;
+  const loc = g["location"] as { origin?: string } | undefined;
+  const origin = loc?.origin;
+  return typeof origin === "string" && origin.length > 0 ? origin : undefined;
+}
+
+/**
+ * Fetches runtime config from the backend on mount, then validates the returned
+ * `baseUrl` is actually reachable.
+ *
+ * Why the probe step matters: `/api/config` is always fetched from the current
+ * origin and always succeeds — but the `baseUrl` it returns could point to the
+ * wrong port (e.g. the Vite dev server) if `BASE_URL` is misconfigured.
+ * Without the probe, all subsequent API calls silently fail with CORS/network
+ * errors and the user sees an empty, unresponsive dashboard (issue #79).
+ *
+ * Probe logic:
+ * - If `baseUrl` matches the current page origin → trivially reachable, skip probe.
+ * - Otherwise → HEAD-request `${baseUrl}/api/config` with a 5 s timeout.
+ *   A connection error here means the baseUrl is wrong.
  */
 export const RuntimeConfigProvider: React.FC<RuntimeConfigProviderProps> = ({
   children,
@@ -55,28 +81,50 @@ export const RuntimeConfigProvider: React.FC<RuntimeConfigProviderProps> = ({
   useEffect(() => {
     const fetchConfig = async () => {
       try {
-        // In development, the proxy handles /api routes
-        // In production, this is the same origin
+        // Step 1: Fetch config from same-origin backend (always succeeds).
         const response = await fetch("/api/config");
         if (!response.ok) {
-          throw new Error(`Failed to fetch config: ${response.status}`);
+          throw new Error(`Failed to fetch runtime config: ${response.status}`);
         }
         const data = (await response.json()) as RuntimeConfig;
-        cachedConfig = data; // Populate module-level cache
+
+        // Step 2: Validate the returned baseUrl is actually reachable.
+        // We only need to probe when baseUrl differs from the current page
+        // origin — same-origin is trivially reachable.
+        const currentOrigin = getCurrentOrigin();
+        if (currentOrigin && data.baseUrl !== currentOrigin) {
+          try {
+            await fetch(`${data.baseUrl}/api/config`, {
+              method: "HEAD",
+              signal: AbortSignal.timeout(5000),
+            });
+          } catch {
+            // baseUrl is not reachable — misconfigured BASE_URL env var.
+            setError(
+              new Error(
+                `BASE_URL is set to "${data.baseUrl}" but it cannot be reached. ` +
+                  `Update BASE_URL in your .env to match the port your container exposes (e.g. ${currentOrigin}).`
+              )
+            );
+            // Don't set config so the error screen renders.
+            return;
+          }
+        }
+
+        cachedConfig = data;
         setConfig(data);
       } catch (error_) {
         console.error("RuntimeConfigProvider: Failed to load config", error_);
-        // Fallback to localhost for development
-        const fallback = { baseUrl: "http://localhost:3000" };
-        cachedConfig = fallback; // Populate cache even on error
-        setConfig(fallback);
-        setError(error_ instanceof Error ? error_ : new Error(String(error_)));
+        setError(
+          error_ instanceof Error ? error_ : new Error(String(error_))
+        );
+        // Do NOT set a fallback — surface the error visibly.
       } finally {
         setIsLoading(false);
       }
     };
 
-    fetchConfig();
+    void fetchConfig();
   }, []);
 
   return (
@@ -91,15 +139,15 @@ export const RuntimeConfigProvider: React.FC<RuntimeConfigProviderProps> = ({
 // =============================================================================
 
 /**
- * Access the runtime config context.
- * Returns { config, isLoading, error }.
+ * Access the runtime config. Consumers should check isLoading first.
  */
 export function useRuntimeConfig(): RuntimeConfig {
   const { config, isLoading } = useContext(RuntimeConfigContext);
 
   if (isLoading || !config) {
-    // Return fallback during loading - consumers should check isLoading
-    return { baseUrl: "http://localhost:3000" };
+    // Return a safe fallback while loading — consumers must check isLoading
+    // if they need to block on the config being available.
+    return { baseUrl: getCurrentOrigin() ?? "http://localhost:3000" };
   }
 
   return config;