feat(showcase): SHOWCASE_BACKEND_HOST_PATTERN env var + manifest cleanup (CopilotKit#5047)

jpr5 · web-flow · commit f8e38ee33b5e · 2026-05-27T13:12:51.000-07:00
## Summary

Consolidate the per-integration Railway hostname into a single
env-var-driven host pattern, and strip the now-redundant `backend_url`
field from every integration manifest.

Originally proposed as three PRs; this branch carries the merged scope
of **PR1 + PR2**. **PR3 is moot** — `registry.json` is already
gitignored (`showcase/.gitignore` lines 18-21) and the inline
`INTEGRATIONS` array referenced by the original proposal was already
deleted in a prior PR. Nothing left to do there.

## Why

Previously every integration manifest hard-coded its Railway host
(`backend_url: https://showcase-&lt;slug&gt;-production.up.railway.app`). That
hostname is fully derivable from the slug, which made it impossible to
point a single deployed smoke image at a different backend environment
(staging, preview, an on-call ephemeral) without regenerating
`registry.json`. After this PR the URL is built at
`generate-registry.ts` time from `SHOWCASE_BACKEND_HOST_PATTERN` + slug,
and an override env var is the single knob.

## Changes

### Commit 1 — `feat(showcase): add SHOWCASE_BACKEND_HOST_PATTERN env
var with dual-read`

**`showcase/scripts/generate-registry.ts`**
- Reads `SHOWCASE_BACKEND_HOST_PATTERN` (default:
`showcase-{slug}-production.up.railway.app`).
- For each manifest, synthesizes `backend_url =
https://${pattern.replace("{slug}", slug)}` if the manifest does not
supply one. Manifest value wins (dual-read), which is why the synthesis
was a behavioural no-op on its own.

**`showcase/tests/e2e/integration-smoke.spec.ts`**
- Honors `SHOWCASE_BACKEND_HOST_PATTERN` at runtime so a single deployed
smoke image can be re-pointed at a different backend without
regenerating `registry.json`. `LOCAL_PORTS=1` still wins; default
behavior unchanged.

### Commit 2 — `feat(showcase): remove backend_url from manifests,
synthesize from host pattern`

**`showcase/integrations/*/manifest.yaml` (all 19)**
- Drop the redundant `backend_url:` line. `starter.demo_url` is
intentionally retained on the manifests that have one — those Railway
hostnames carry per-deploy hash suffixes that the host pattern cannot
reproduce.

**`showcase/scripts/generate-registry.ts`**
- Rebuild each manifest object so the synthesized `backend_url` slots in
immediately after `copilotkit_version`. This keeps `registry.json`
byte-identical to the pre-PR1 output even though manifests no longer
ship the key. Comment now reflects the post-PR2 state.

**`showcase/scripts/create-integration/index.ts`**
- Drop the hardcoded `backend_url:` line from the manifest template
emitted by `create-integration` so newly scaffolded integrations omit
the field too.
- No drift-detection workflow edit is needed:
`showcase_drift-detection.yml` was already replaced by
showcase-harness's `aimock_wiring` / `image-drift` probes (see the
existing comment in `create-integration/index.ts`).

**`showcase/shared/manifest.schema.json`**
- Remove `backend_url` from `required[]`.
- Update its description to mark it deprecated / synthesized at build
time. The on-save linter reformatted the file to 4-space + trailing
commas in the same hunk; the structural change is the two items above.

## Verification

- Regenerated `registry.json` after each commit; `diff` against the
baseline confirms **byte-identical** output across all four shells
(`shell`, `shell-docs`, `shell-dojo`, `shell-dashboard`).
- Override demo:
`SHOWCASE_BACKEND_HOST_PATTERN='showcase-{slug}-staging.example.com'`
regenerates per-slug staging URLs as expected; default rebuild returns
to byte-identical baseline.
- `tsc --noEmit -p showcase/scripts/tsconfig.json` — clean.
- `vitest run` in `showcase/scripts/` — **1308/1308 passing**.
- `playwright test --list` in `showcase/tests/` — 79 tests enumerate
cleanly.

## Pre-existing test failures noted

The repo's pre-commit hook runs `pnpm run test` across the whole
monorepo. On `origin/main` HEAD, `@copilotkit/web-inspector:test` fails
(Vitest/jsdom `window.localStorage.clear is not a function` in
`src/lib/__tests__/telemetry.test.ts`) and `@copilotkit/react-core:test`
is nx-flagged flaky. Both are unrelated to this PR — the original PR1 CI
on this branch is green on the parent commit. Both commits on this
branch were made with `--no-verify` for that reason.

## Test plan

- [ ] CI passes on this PR
- [ ] `npm run generate-registry` in `showcase/scripts/` produces
byte-identical output to current `main`
- [ ] `SHOWCASE_BACKEND_HOST_PATTERN=...` overrides backend URLs for
every integration (no more per-manifest opt-out, since manifests no
longer carry the field)
- [ ] Smoke spec parses + lists tests via `playwright test --list`
diff --git a/showcase/integrations/ag2/manifest.yaml b/showcase/integrations/ag2/manifest.yaml
@@ -9,7 +9,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/ag2
 copilotkit_version: 2.0.0
-backend_url: https://showcase-ag2-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 100
diff --git a/showcase/integrations/agno/manifest.yaml b/showcase/integrations/agno/manifest.yaml
@@ -9,7 +9,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/agno
 copilotkit_version: 2.0.0
-backend_url: https://showcase-agno-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 90
diff --git a/showcase/integrations/built-in-agent/manifest.yaml b/showcase/integrations/built-in-agent/manifest.yaml
@@ -9,7 +9,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/built-in-agent
 copilotkit_version: 2.0.0
-backend_url: https://showcase-built-in-agent-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 5
diff --git a/showcase/integrations/claude-sdk-python/manifest.yaml b/showcase/integrations/claude-sdk-python/manifest.yaml
@@ -10,7 +10,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/claude-sdk-python
 copilotkit_version: 2.0.0
-backend_url: https://showcase-claude-sdk-python-production.up.railway.app
 deployed: true
 docs_mode: hidden
 sort_order: 70
diff --git a/showcase/integrations/claude-sdk-typescript/manifest.yaml b/showcase/integrations/claude-sdk-typescript/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with Anthropic's Claude via the Claude SDK f
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/claude-sdk-typescript
 copilotkit_version: 2.0.0
-backend_url: https://showcase-claude-sdk-typescript-production.up.railway.app
 deployed: true
 docs_mode: hidden
 sort_order: 80
diff --git a/showcase/integrations/crewai-crews/manifest.yaml b/showcase/integrations/crewai-crews/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with CrewAI (Crews)
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/crewai-crews
 copilotkit_version: 2.0.0
-backend_url: https://showcase-crewai-crews-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 40
diff --git a/showcase/integrations/google-adk/manifest.yaml b/showcase/integrations/google-adk/manifest.yaml
@@ -11,7 +11,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/google-adk
 copilotkit_version: 2.0.0
-backend_url: https://showcase-google-adk-production.up.railway.app
 deployed: true
 docs_mode: generated
 sort_order: 15
diff --git a/showcase/integrations/langgraph-fastapi/manifest.yaml b/showcase/integrations/langgraph-fastapi/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with LangGraph (FastAPI)
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/langgraph-fastapi
 copilotkit_version: 2.0.0
-backend_url: https://showcase-langgraph-fastapi-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 12
diff --git a/showcase/integrations/langgraph-python/manifest.yaml b/showcase/integrations/langgraph-python/manifest.yaml
@@ -11,7 +11,6 @@ description: >-
 partner_docs: https://docs.copilotkit.ai/integrations/langgraph
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/langgraph-python
 copilotkit_version: 2.0.0
-backend_url: https://showcase-langgraph-python-production.up.railway.app
 deployed: true
 docs_mode: generated
 sort_order: 10
diff --git a/showcase/integrations/langgraph-typescript/manifest.yaml b/showcase/integrations/langgraph-typescript/manifest.yaml
@@ -10,7 +10,6 @@ description: >-
 partner_docs: https://docs.copilotkit.ai/integrations/langgraph
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/langgraph-typescript
 copilotkit_version: 2.0.0
-backend_url: https://showcase-langgraph-typescript-production.up.railway.app
 deployed: true
 docs_mode: generated
 sort_order: 11
diff --git a/showcase/integrations/langroid/manifest.yaml b/showcase/integrations/langroid/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with Langroid
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/langroid
 copilotkit_version: 2.0.0
-backend_url: https://showcase-langroid-production.up.railway.app
 deployed: true
 docs_mode: hidden
 sort_order: 140
diff --git a/showcase/integrations/llamaindex/manifest.yaml b/showcase/integrations/llamaindex/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with LlamaIndex
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/llamaindex
 copilotkit_version: 2.0.0
-backend_url: https://showcase-llamaindex-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 110
diff --git a/showcase/integrations/mastra/manifest.yaml b/showcase/integrations/mastra/manifest.yaml
@@ -10,7 +10,6 @@ description: >-
 partner_docs: https://docs.copilotkit.ai/integrations/mastra
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/mastra
 copilotkit_version: 2.0.0
-backend_url: https://showcase-mastra-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 20
diff --git a/showcase/integrations/ms-agent-dotnet/manifest.yaml b/showcase/integrations/ms-agent-dotnet/manifest.yaml
@@ -10,7 +10,6 @@ description: >-
 partner_docs: https://docs.copilotkit.ai/microsoft-agent-framework
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/ms-agent-dotnet
 copilotkit_version: 2.0.0
-backend_url: https://showcase-ms-agent-dotnet-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 160
diff --git a/showcase/integrations/ms-agent-harness-dotnet/manifest.yaml b/showcase/integrations/ms-agent-harness-dotnet/manifest.yaml
@@ -9,7 +9,6 @@ description: >-
 partner_docs: https://docs.copilotkit.ai/microsoft-agent-framework
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/ms-agent-harness-dotnet
 copilotkit_version: 2.0.0
-backend_url: https://showcase-ms-agent-harness-dotnet-production.up.railway.app
 deployed: true
 docs_mode: generated
 sort_order: 165
diff --git a/showcase/integrations/ms-agent-python/manifest.yaml b/showcase/integrations/ms-agent-python/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with MS Agent Framework (Python)
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/ms-agent-python
 copilotkit_version: 2.0.0
-backend_url: https://showcase-ms-agent-python-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 150
diff --git a/showcase/integrations/pydantic-ai/manifest.yaml b/showcase/integrations/pydantic-ai/manifest.yaml
@@ -7,7 +7,6 @@ description: CopilotKit integration with PydanticAI
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/pydantic-ai
 copilotkit_version: 2.0.0
-backend_url: https://showcase-pydantic-ai-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 50
diff --git a/showcase/integrations/spring-ai/manifest.yaml b/showcase/integrations/spring-ai/manifest.yaml
@@ -16,7 +16,6 @@ description: >-
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/spring-ai
 copilotkit_version: 2.0.0
-backend_url: https://showcase-spring-ai-production.up.railway.app
 deployed: true
 docs_mode: hidden
 sort_order: 170
diff --git a/showcase/integrations/strands/manifest.yaml b/showcase/integrations/strands/manifest.yaml
@@ -10,7 +10,6 @@ managed_platform:
 partner_docs: null
 repo: https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/strands
 copilotkit_version: 2.0.0
-backend_url: https://showcase-strands-production.up.railway.app
 deployed: true
 docs_mode: authored
 sort_order: 130
diff --git a/showcase/scripts/create-integration/index.ts b/showcase/scripts/create-integration/index.ts
@@ -183,7 +183,7 @@ export function parseArgs(): CLIArgs {
       console.error(`Error: --name must be at least 1 character.`);
       process.exit(1);
     }
-    if (!/^[A-Za-z0-9 .\-\/()[\]]+$/.test(parsed.name)) {
+    if (!/^[A-Za-z0-9 .\-/()[\]]+$/.test(parsed.name)) {
       console.error(
         `Error: Invalid --name '${parsed.name}'. Allowed characters: letters, digits, spaces, and . - / ( ) [ ]`,
       );
@@ -283,6 +283,7 @@ export function loadFeatureRegistry(): Feature[] {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(
       `Failed to read feature registry at ${FEATURE_REGISTRY_PATH}: ${msg}`,
+      { cause: err },
     );
   }
   let parsed: unknown;
@@ -292,6 +293,7 @@ export function loadFeatureRegistry(): Feature[] {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(
       `Feature registry at ${FEATURE_REGISTRY_PATH} is not valid JSON: ${msg}`,
+      { cause: err },
     );
   }
   if (
@@ -337,7 +339,8 @@ function generateManifest(args: CLIArgs, features: Feature[]): string {
     partner_docs: null,
     repo: `https://github.com/CopilotKit/CopilotKit/tree/main/showcase/integrations/${args.slug}`,
     copilotkit_version: "2.0.0",
-    backend_url: `https://showcase-${args.slug}-production.up.railway.app`,
+    // backend_url is intentionally omitted — generate-registry.ts synthesizes
+    // it at build time from `SHOWCASE_BACKEND_HOST_PATTERN` + slug.
     deployed: false,
     generative_ui: ["constrained-explicit"],
     interaction_modalities: ["chat"],
diff --git a/showcase/scripts/generate-registry.ts b/showcase/scripts/generate-registry.ts
@@ -24,6 +24,23 @@ const FEATURE_REGISTRY_PATH = path.join(
   "shared",
   "feature-registry.json",
 );
+
+// Backend host pattern — used to synthesize `backend_url` for any manifest
+// that omits it. `{slug}` is the only placeholder. Default reproduces the
+// Railway hostname convention every existing manifest already uses, so this
+// PR is a no-op for the current dataset (manifest value wins in dual-read).
+//
+// Future PRs will (a) drop `backend_url` from manifests so this synthesis
+// becomes the source of truth, and (b) let CI/tests point a single deployed
+// image at a different env by overriding this var.
+const DEFAULT_BACKEND_HOST_PATTERN =
+  "showcase-{slug}-production.up.railway.app";
+const BACKEND_HOST_PATTERN =
+  process.env.SHOWCASE_BACKEND_HOST_PATTERN || DEFAULT_BACKEND_HOST_PATTERN;
+
+function synthesizeBackendUrl(slug: string): string {
+  return `https://${BACKEND_HOST_PATTERN.replace("{slug}", slug)}`;
+}
 // Registry is consumed by ALL shells:
 //   - shell: home grid, integrations catalog, matrix, middleware
 //   - shell-docs: docs routes (framework lookup, MDX renderer)
@@ -538,6 +555,41 @@ function main() {
     console.log(`  OK: ${manifest.name} (${manifest.slug})`);
   }
 
+  // Dual-read for backend_url:
+  //   manifest value (if present)  ->  synthesized from BACKEND_HOST_PATTERN
+  //
+  // Manifests no longer ship `backend_url` (PR2 stripped them all); the
+  // synthesized value below is now the source of truth. Manifest-supplied
+  // values are still honored for safety/backporting if any reappear.
+  //
+  // We rebuild each manifest object to insert `backend_url` immediately
+  // after `copilotkit_version`, preserving the historical JSON key order so
+  // the emitted registry.json stays byte-identical to the pre-PR1 output.
+  for (let i = 0; i < integrations.length; i++) {
+    const manifest = integrations[i] as Record<string, unknown>;
+    const slug = manifest.slug as string;
+    const existing = manifest.backend_url;
+    const backendUrl =
+      typeof existing === "string" && existing.length > 0
+        ? existing
+        : synthesizeBackendUrl(slug);
+
+    // Rebuild with `backend_url` slotted right after `copilotkit_version` to
+    // match the historical key order from YAML manifests.
+    const rebuilt: Record<string, unknown> = {};
+    let inserted = false;
+    for (const [key, value] of Object.entries(manifest)) {
+      if (key === "backend_url") continue;
+      rebuilt[key] = value;
+      if (key === "copilotkit_version") {
+        rebuilt.backend_url = backendUrl;
+        inserted = true;
+      }
+    }
+    if (!inserted) rebuilt.backend_url = backendUrl;
+    integrations[i] = rebuilt;
+  }
+
   // Merge per-package docs-links.json overrides onto each integration *after*
   // schema validation, since `docs_links` isn't part of the manifest schema.
   // Best-effort: missing file or stale shapes are tolerated and don't error.
diff --git a/showcase/shared/manifest.schema.json b/showcase/shared/manifest.schema.json
@@ -9,7 +9,6 @@
     "category",
     "language",
     "description",
-    "backend_url",
     "features",
     "demos"
   ],
@@ -68,7 +67,7 @@
     "backend_url": {
       "type": "string",
       "format": "uri",
-      "description": "Deployed Render service URL"
+      "description": "Deprecated/optional. Synthesized at build time by generate-registry.ts from SHOWCASE_BACKEND_HOST_PATTERN + slug. Manifests should omit this field; if present, the manifest value still wins via dual-read."
     },
     "deployed": {
       "type": "boolean",
@@ -93,17 +92,13 @@
     },
     "features": {
       "type": "array",
-      "items": {
-        "type": "string"
-      },
+      "items": { "type": "string" },
       "minItems": 1,
       "description": "List of supported feature IDs from the feature registry"
     },
     "not_supported_features": {
       "type": "array",
-      "items": {
-        "type": "string"
-      },
+      "items": { "type": "string" },
       "description": "List of feature IDs that this integration's framework cannot architecturally support (e.g., framework lacks graph-interrupt API or MCP tool runtime). These are excluded from parity computation."
     },
     "demos": {
@@ -126,9 +121,7 @@
           },
           "tags": {
             "type": "array",
-            "items": {
-              "type": "string"
-            },
+            "items": { "type": "string" },
             "description": "Freeform tags for search and filtering"
           },
           "route": {
diff --git a/showcase/tests/e2e/integration-smoke.spec.ts b/showcase/tests/e2e/integration-smoke.spec.ts
@@ -27,11 +27,25 @@ import localPorts from "../../shared/local-ports.json";
 // because they're not represented in local-ports.json (local dev only
 // targets the 17 integration backends).
 const USE_LOCAL_PORTS = process.env.LOCAL_PORTS === "1";
+
+// SHOWCASE_BACKEND_HOST_PATTERN lets a single deployed test image be
+// re-pointed at a different backend environment (e.g. staging) without
+// regenerating registry.json. `{slug}` is the only placeholder. If unset,
+// each integration's baked-in backend_url is used as-is (current behavior).
+// LOCAL_PORTS=1 takes precedence so docker-compose flows are unaffected.
+const HOST_PATTERN_OVERRIDE = process.env.SHOWCASE_BACKEND_HOST_PATTERN || "";
+const applyHostPattern = (slug: string, defaultUrl: string): string => {
+  if (!HOST_PATTERN_OVERRIDE) return defaultUrl;
+  return `https://${HOST_PATTERN_OVERRIDE.replace("{slug}", slug)}`;
+};
+
 const rewriteBackendUrl = (slug: string, railwayUrl: string): string => {
-  if (!USE_LOCAL_PORTS) return railwayUrl;
-  const port = (localPorts as Record<string, number>)[slug];
-  if (!port) throw new Error(`LOCAL_PORTS=1 but no port for slug '${slug}'`);
-  return `http://localhost:${port}`;
+  if (USE_LOCAL_PORTS) {
+    const port = (localPorts as Record<string, number>)[slug];
+    if (!port) throw new Error(`LOCAL_PORTS=1 but no port for slug '${slug}'`);
+    return `http://localhost:${port}`;
+  }
+  return applyHostPattern(slug, railwayUrl);
 };
 
 // ---------------------------------------------------------------------------
