Reactv1.2.1Frontend

React SDK

Add feature flags to your React application with hooks and context providers. Supports real-time updates, SSR, and TypeScript.

Installation

npm install @rollgate/sdk-react
# or
yarn add @rollgate/sdk-react
# or
pnpm add @rollgate/sdk-react

Quick Start

1. Add the Provider

Wrap your application with RollgateProvider:

app/layout.tsx

import { RollgateProvider } from '@rollgate/sdk-react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <RollgateProvider
          apiKey={process.env.NEXT_PUBLIC_ROLLGATE_API_KEY!}
          baseUrl="https://api.rollgate.io"
        >
          {children}
        </RollgateProvider>
      </body>
    </html>
  );
}

2. Use the Hook

Access flags in your components with useFlag:

components/Feature.tsx

import { useFlag } from '@rollgate/sdk-react';

export function Feature() {
  const isEnabled = useFlag('my-feature', false);

  if (!isEnabled) {
    return null;
  }

  return <NewFeature />;
}

Provider Props

Prop	Type	Default	Description
apiKey	string	required	Your Rollgate client API key
baseUrl	string	'https://api.rollgate.io'	Rollgate API base URL
refreshInterval	number	30000	Polling interval in milliseconds
enableStreaming	boolean	false	Use SSE for real-time updates (opt-in)
streaming	boolean	false	Alias for enableStreaming
user	UserContext	undefined	Initial user context for targeting

Hooks

useFlag

Check if a single flag is enabled:

const isEnabled = useFlag('flag-key', defaultValue);

Prop	Type	Default	Description
flagKey	string	required	The flag key to check
defaultValue	boolean	false	Value to return if flag not found

useFlags

Get all flags at once:

const { flags, isLoading, error } = useFlags();

// Access individual flags
if (flags['new-feature']) {
  // ...
}

useRollgate

Access the full Rollgate context for advanced use cases:

const {
  flags,
  isLoading,
  error,
  identify,  // Set user context
  refresh,   // Force refresh flags
} = useRollgate();

// Identify user after login
await identify({
  id: 'user-123',
  email: '[email protected]',
  attributes: { plan: 'pro' }
});

User Targeting

Pass user information to enable targeting rules, percentage rollout, and target user lists. The SDK sends this context to the server where rules are evaluated securely.

User Context Structure

interface UserContext {
  id: string;           // Required for percentage rollout
  email?: string;       // For email-based targeting
  attributes?: {        // Any custom attributes for targeting rules
    plan?: string;      // e.g., "free", "pro", "growth"
    country?: string;   // e.g., "IT", "US", "DE"
    company?: string;   // e.g., "Acme Inc"
    app_version?: string; // e.g., "2.1.0" (for semver comparisons)
    [key: string]: string | number | boolean;
  };
}

Setting User Context

// Option 1: In provider (known user at startup)
<RollgateProvider
  apiKey="..."
  user={{
    id: 'user-123',
    email: '[email protected]',
    attributes: {
      plan: 'pro',
      country: 'IT',
      company: 'Acme Inc',
      app_version: '2.1.0'
    }
  }}
>

// Option 2: After authentication (dynamic)
const { identify } = useRollgate();

useEffect(() => {
  if (user) {
    identify({
      id: user.id,
      email: user.email,
      attributes: {
        plan: user.subscription.plan,
        country: user.profile.country,
        company: user.organization?.name,
        app_version: APP_VERSION
      }
    });
  }
}, [user]);

Targeting Rules Example

With the user context above, your targeting rules can match on any attribute:

Example: Pro Italian Users on v2+

Dashboard rule configuration:

Rule: "Pro Italian Users on v2+"
Conditions (all must match):
  - plan IN "pro,growth"
  - country EQUALS "IT"
  - app_version SEMVER_GTE "2.0.0"

// This user will match:
{
  id: "user-123",
  attributes: {
    plan: "pro",      // ✓ in [pro, growth]
    country: "IT",     // ✓ equals IT
    app_version: "2.1.0" // ✓ >= 2.0.0
  }
}

Security: Rules are evaluated server-side. Users cannot see or manipulate the targeting logic - they only receive the final boolean result.

Server-Side Rendering

For SSR with Next.js, fetch flags on the server and pass them as initial state:

app/page.tsx

import { getFlags } from '@/lib/rollgate-server';

export default async function Page() {
  const flags = await getFlags();

  return (
    <RollgateProvider
      apiKey="..."
      initialFlags={flags}
    >
      <MyApp />
    </RollgateProvider>
  );
}

TypeScript

The SDK is fully typed. Define your flag keys for type safety:

// types/flags.ts
export type FlagKey =
  | 'new-checkout'
  | 'dark-mode'
  | 'beta-features';

// Usage
const isEnabled = useFlag<FlagKey>('new-checkout');

Node.js SDK

Server-side feature flags with circuit breaker

Proxy Pattern

Scale React apps to millions of users