You are an expert in integrating Unleash for feature flag management.

## Key Points

- **Exposing the server API token to frontend clients** -- The server token has administrative access. Use Unleash Edge with a frontend-specific token for all browser and mobile clients.
- **Not passing context with evaluations** -- Without userId, sessionId, and custom properties in the context, gradual rollouts return inconsistent results and targeting rules do not match.
- **Use Unleash Edge for frontend clients** — never expose the server API token to browsers. Edge handles token validation, caching, and reduces load on the Unleash API.
- **Pass rich context on every evaluation** — include userId, sessionId, and custom properties so that gradual rollouts, constraints, and segments work correctly.
- **Organize flags with projects and tags** — group related flags by team or domain using Unleash projects, and use tags to mark lifecycle stages (experiment, permanent, tech-debt).

Unleash — Feature Flags

You are an expert in integrating Unleash for feature flag management.

Core Philosophy

Unleash separates flag definition from flag evaluation. The Unleash API server stores flag configurations centrally, while SDKs evaluate flags locally based on periodically synced definitions. This architecture means flag evaluation is fast (no network round-trip per check), resilient (the SDK works with cached state during server outages), and scalable (adding more application instances does not increase load on the server proportionally). The API server is the source of truth; the SDKs are distributed evaluation engines.

Activation strategies are Unleash's core abstraction. Instead of a simple on/off toggle, each flag has one or more strategies that define when and for whom the flag is active. Strategies can be based on user IDs, percentages, date ranges, host names, or custom criteria. Multiple strategies can be attached to a single flag -- if any strategy matches, the flag is on. This composable approach lets you express complex rollout rules (e.g., "100% for employees, 10% gradual rollout for external users, only in US region") without writing conditional logic in your application.

Frontend clients must never talk directly to the Unleash API server. The server API token has administrative capabilities and must not be exposed in browser or mobile code. Unleash Edge (or the legacy Unleash Proxy) sits between frontend clients and the API, handling token validation, caching, and flag evaluation at the edge with minimal latency. This architecture is not optional -- it is a security requirement.

Anti-Patterns

• Evaluating flags before the ready event fires -- The SDK fetches flags asynchronously on startup. Evaluating before ready returns default values for all flags, which can silently disable features during cold starts.
• Exposing the server API token to frontend clients -- The server token has administrative access. Use Unleash Edge with a frontend-specific token for all browser and mobile clients.
• Not passing context with evaluations -- Without userId, sessionId, and custom properties in the context, gradual rollouts return inconsistent results and targeting rules do not match.
• Ignoring SDK disconnection warnings -- If the Unleash server is unreachable, the SDK uses stale flag state indefinitely. This is by design, but prolonged disconnection means flag changes are not propagating. Monitor error events and alert on extended outages.
• Accumulating stale flags without cleanup -- Feature flags that are permanently on or permanently off are dead code. Regularly audit flags and remove those that have completed their rollout lifecycle.

Overview

Unleash is an open-source feature management platform that gives teams full control over feature rollouts through activation strategies. It supports gradual rollouts, user targeting, A/B variants, and environment-based toggling. Unleash can be self-hosted or used via the managed Unleash Edge service. Its architecture separates the Unleash API server (central flag storage) from lightweight SDKs that evaluate flags locally, minimizing latency and ensuring flags work even when the server is unreachable.

Setup & Configuration

Node.js Server SDK

import { initialize, isEnabled, getVariant } from "unleash-client";

const unleash = initialize({
  url: process.env.UNLEASH_API_URL!,       // e.g. "https://unleash.example.com/api"
  appName: "my-service",
  customHeaders: {
    Authorization: process.env.UNLEASH_API_TOKEN!,
  },
  refreshInterval: 15_000,  // poll interval in ms
});

unleash.on("ready", () => {
  console.log("Unleash client ready");
});

unleash.on("error", (err) => {
  console.error("Unleash error:", err);
});

React Frontend SDK

import { FlagProvider, useFlag, useVariant } from "@unleash/proxy-client-react";

// The frontend SDK talks to Unleash Edge or the Unleash Proxy, not the API directly
const config = {
  url: "https://unleash-edge.example.com/api/frontend",
  clientKey: process.env.REACT_APP_UNLEASH_FRONTEND_KEY!,
  appName: "my-react-app",
  refreshInterval: 30,
};

function App() {
  return (
    <FlagProvider config={config}>
      <MainContent />
    </FlagProvider>
  );
}

function MainContent() {
  const newDashboard = useFlag("new-dashboard");
  const variant = useVariant("checkout-flow");

  if (!newDashboard) return <LegacyDashboard />;

  return variant.name === "streamlined"
    ? <StreamlinedCheckout />
    : <StandardCheckout />;
}

Self-Hosted Docker Setup

# docker-compose.yml
version: "3.9"
services:
  unleash:
    image: unleashorg/unleash-server:latest
    ports:
      - "4242:4242"
    environment:
      DATABASE_URL: postgres://unleash:password@db:5432/unleash
      DATABASE_SSL: "false"
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: unleash
      POSTGRES_PASSWORD: password
      POSTGRES_DB: unleash
    volumes:
      - unleash_data:/var/lib/postgresql/data

volumes:
  unleash_data:

Core Patterns

Activation Strategies

Unleash uses activation strategies to decide when a flag is enabled. Multiple strategies can be attached to a single flag — if any strategy matches, the flag is on.

// Standard toggle — simple on/off
const enabled = isEnabled("my-feature");

// Contextual evaluation — pass user/session data for targeting
import { Context } from "unleash-client";

const context: Context = {
  userId: user.id,
  sessionId: req.sessionId,
  remoteAddress: req.ip,
  properties: {
    plan: user.plan,
    region: user.region,
  },
};

const showFeature = isEnabled("premium-export", context);

Gradual Rollout

// Configure in Unleash UI or API:
// Strategy: "flexibleRollout"
// Parameters: rollout=25, stickiness=userId, groupId=beta-features
//
// SDK evaluation is automatic — just pass context:
const context = { userId: user.id };
const inRollout = isEnabled("new-pricing-page", context);

Variants for A/B Testing

import { getVariant } from "unleash-client";

const variant = getVariant("onboarding-flow", context);

switch (variant.name) {
  case "wizard":
    return <WizardOnboarding payload={variant.payload} />;
  case "checklist":
    return <ChecklistOnboarding payload={variant.payload} />;
  default:
    return <DefaultOnboarding />;
}

Constraints

Constraints narrow when a strategy applies — e.g., only for specific environments, user segments, or date ranges.

// Configured in Unleash UI:
// Strategy: gradualRollout (50%)
// Constraint: currentTime DATE_AFTER 2025-03-01
// Constraint: properties.plan IN ["pro", "enterprise"]
//
// SDK handles constraint evaluation automatically when context is provided:
const context = {
  userId: user.id,
  properties: { plan: user.plan },
};
const enabled = isEnabled("billing-v2", context);

Unleash Edge for Low-Latency Frontend

// Unleash Edge sits between clients and the Unleash API
// It caches flag state and evaluates flags at the edge
// Configure Edge via environment variables:
// UPSTREAM_URL=https://unleash.example.com
// TOKENS=*:production.frontend-token-here

// Frontend SDKs point to Edge instead of the API
const config = {
  url: "https://edge.example.com/api/frontend",
  clientKey: "production.frontend-token-here",
  appName: "web-app",
};

Best Practices

• Use Unleash Edge for frontend clients — never expose the server API token to browsers. Edge handles token validation, caching, and reduces load on the Unleash API.
• Pass rich context on every evaluation — include userId, sessionId, and custom properties so that gradual rollouts, constraints, and segments work correctly.
• Organize flags with projects and tags — group related flags by team or domain using Unleash projects, and use tags to mark lifecycle stages (experiment, permanent, tech-debt).

Common Pitfalls

• Forgetting to wait for ready event — the SDK fetches flags asynchronously on startup. Evaluating flags before ready fires returns default values, which can silently disable features during cold starts.
• Stale flags in long-running processes — if the Unleash server is unreachable, the SDK uses its last known state. This is a feature, but it means stale flags can persist indefinitely. Monitor the warn and error events and set up alerts for prolonged disconnection.