feat: add Unleash feature flag integration to frontend (#655)

Adds feature flag UI and React Query hooks:
- Unleash React SDK provider with proxy configuration
- Feature flags settings UI in workspace settings
- useWorkspaceFlag hook for workspace-scoped evaluation
- API routes for flag evaluation and override management
- Batch save pattern for admin UI

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: maskarb

components/frontend/.env.example

@@ -32,6 +32,16 @@ MAX_UPLOAD_SIZE_IMAGES=3145728
 IMAGE_COMPRESSION_TARGET=358400
 
 
+# Unleash feature flags (optional)
+# When set, the frontend proxy /api/feature-flags will forward to Unleash.
+# UNLEASH_URL=https://unleash.example.com
+# UNLEASH_CLIENT_KEY=your-frontend-api-token
+# UNLEASH_APP_NAME=ambient-code-platform
+# NEXT_PUBLIC_UNLEASH_ENV_CONTEXT_FIELD: Environment value sent in SDK context (default: development)
+# Note: This does NOT select the Unleash environment - that's determined by the token scope.
+# This is only used for strategy constraints that check context.environment.
+# NEXT_PUBLIC_UNLEASH_ENV_CONTEXT_FIELD=development
+
 # Langfuse Configuration for User Feedback
 # These are used by the /api/feedback route to submit user feedback scores
 # Get your keys from your Langfuse instance: Settings > API Keys

components/frontend/package-lock.json

@@ -18,11 +18,14 @@
     "@radix-ui/react-progress": "^1.1.7",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-switch": "^1.1.3",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.15",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@tanstack/react-query": "^5.90.2",
     "@tanstack/react-query-devtools": "^5.90.2",
+    "@unleash/proxy-client-react": "^5.0.1",
+    "unleash-proxy-client": "^3.6.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",

components/frontend/package.json

@@ -0,0 +1,48 @@
+import { env } from '@/lib/env';
+import { NextRequest } from 'next/server';
+
+/**
+ * POST /api/feature-flags/client/metrics
+ * Proxies usage metrics from the Unleash SDK to the Unleash server.
+ * This enables impression data and usage tracking in Unleash.
+ */
+export async function POST(request: NextRequest) {
+  const baseUrl = env.UNLEASH_URL?.replace(/\/$/, '');
+  const clientKey = env.UNLEASH_CLIENT_KEY;
+
+  // If Unleash isn't configured, just acknowledge the request
+  if (!baseUrl || !clientKey) {
+    console.log('[Unleash Metrics] Unleash not configured, ignoring metrics');
+    return new Response(null, { status: 202 });
+  }
+
+  const url = new URL('/api/frontend/client/metrics', baseUrl);
+
+  try {
+    const body = await request.json();
+    console.log('[Unleash Metrics] Forwarding metrics to:', url.toString());
+    console.log('[Unleash Metrics] Payload:', JSON.stringify(body, null, 2));
+
+    const res = await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        Authorization: clientKey,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorText = await res.text();
+      console.error('[Unleash Metrics] Error:', res.status, errorText);
+      // Still return 202 to not break the client
+      return new Response(null, { status: 202 });
+    }
+
+    console.log('[Unleash Metrics] Success:', res.status);
+    return new Response(null, { status: 202 });
+  } catch (error) {
+    console.error('[Unleash Metrics] Fetch error:', error);
+    return new Response(null, { status: 202 });
+  }
+}

components/frontend/src/app/api/feature-flags/client/metrics/route.ts

@@ -0,0 +1,43 @@
+import { env } from '@/lib/env';
+import { NextRequest } from 'next/server';
+
+/**
+ * POST /api/feature-flags/client/register
+ * Proxies client registration from the Unleash SDK to the Unleash server.
+ * This allows Unleash to track connected clients/applications.
+ */
+export async function POST(request: NextRequest) {
+  const baseUrl = env.UNLEASH_URL?.replace(/\/$/, '');
+  const clientKey = env.UNLEASH_CLIENT_KEY;
+
+  // If Unleash isn't configured, just acknowledge the request
+  if (!baseUrl || !clientKey) {
+    return new Response(null, { status: 202 });
+  }
+
+  const url = new URL('/api/frontend/client/register', baseUrl);
+
+  try {
+    const body = await request.json();
+
+    const res = await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        Authorization: clientKey,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      console.error('Unleash register proxy error:', res.status, await res.text());
+      // Still return 202 to not break the client
+      return new Response(null, { status: 202 });
+    }
+
+    return new Response(null, { status: 202 });
+  } catch (error) {
+    console.error('Unleash register proxy fetch error:', error);
+    return new Response(null, { status: 202 });
+  }
+}

components/frontend/src/app/api/feature-flags/client/register/route.ts

@@ -0,0 +1,45 @@
+import { env } from '@/lib/env';
+import { NextRequest } from 'next/server';
+
+/**
+ * GET /api/feature-flags
+ * Proxies to Unleash Frontend API when UNLEASH_URL and UNLEASH_CLIENT_KEY are set.
+ * Returns empty toggles when Unleash is not configured (SDK still works, all flags off).
+ * Used by @unleash/proxy-client-react so the client never sees the real Unleash URL or key.
+ */
+export async function GET(request: NextRequest) {
+  const baseUrl = env.UNLEASH_URL?.replace(/\/$/, '');
+  const clientKey = env.UNLEASH_CLIENT_KEY;
+
+  if (!baseUrl || !clientKey) {
+    return Response.json({ toggles: [] });
+  }
+
+  const url = new URL('/api/frontend', baseUrl);
+  // Forward query params (e.g. projectId) if needed for strategies
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  try {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        Authorization: clientKey,
+        'Content-Type': 'application/json',
+      },
+      next: { revalidate: 15 },
+    });
+
+    if (!res.ok) {
+      console.error('Unleash proxy error:', res.status, await res.text());
+      return Response.json({ toggles: [] });
+    }
+
+    const data = await res.json();
+    return Response.json(data);
+  } catch (error) {
+    console.error('Unleash proxy fetch error:', error);
+    return Response.json({ toggles: [] });
+  }
+}

components/frontend/src/app/api/feature-flags/route.ts

@@ -0,0 +1,37 @@
+import { BACKEND_URL } from "@/lib/config";
+import { buildForwardHeadersAsync } from "@/lib/auth";
+
+/**
+ * POST /api/projects/:projectName/feature-flags/:flagName/disable
+ * Proxies to backend to disable a feature flag in Unleash
+ */
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ name: string; flagName: string }> }
+) {
+  try {
+    const { name: projectName, flagName } = await params;
+    const headers = await buildForwardHeadersAsync(request);
+
+    const response = await fetch(
+      `${BACKEND_URL}/projects/${encodeURIComponent(projectName)}/feature-flags/${encodeURIComponent(flagName)}/disable`,
+      {
+        method: "POST",
+        headers,
+      }
+    );
+
+    const data = await response.text();
+
+    return new Response(data, {
+      status: response.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch (error) {
+    console.error("Failed to disable feature flag:", error);
+    return Response.json(
+      { error: "Failed to disable feature flag" },
+      { status: 500 }
+    );
+  }
+}

components/frontend/src/app/api/projects/[name]/feature-flags/[flagName]/disable/route.ts

@@ -0,0 +1,37 @@
+import { BACKEND_URL } from "@/lib/config";
+import { buildForwardHeadersAsync } from "@/lib/auth";
+
+/**
+ * POST /api/projects/:projectName/feature-flags/:flagName/enable
+ * Proxies to backend to enable a feature flag in Unleash
+ */
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ name: string; flagName: string }> }
+) {
+  try {
+    const { name: projectName, flagName } = await params;
+    const headers = await buildForwardHeadersAsync(request);
+
+    const response = await fetch(
+      `${BACKEND_URL}/projects/${encodeURIComponent(projectName)}/feature-flags/${encodeURIComponent(flagName)}/enable`,
+      {
+        method: "POST",
+        headers,
+      }
+    );
+
+    const data = await response.text();
+
+    return new Response(data, {
+      status: response.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch (error) {
+    console.error("Failed to enable feature flag:", error);
+    return Response.json(
+      { error: "Failed to enable feature flag" },
+      { status: 500 }
+    );
+  }
+}