@getflaggy/sdk

JavaScript/React SDK for the Flaggy feature flag server.

• Zero runtime dependencies
• Server-side evaluation with local cache
• Real-time updates via SSE
• React bindings with useFlag hook
• TypeScript, dual ESM/CJS

Install

npm install @getflaggy/sdk

React

Setup

Wrap your app with FlaggyProvider:

import { FlaggyProvider } from '@getflaggy/sdk/react';

function App() {
  return (
    <FlaggyProvider
      serverUrl="https://flaggy.example.com"
      apiKey="your-api-key"
      flags={['show-banner', 'dark-mode']}
      context={{ userId: '123', plan: 'pro' }}
      onError={(err) => console.error(err)}
    >
      <MyApp />
    </FlaggyProvider>
  );
}

Read a flag

import { useFlag } from '@getflaggy/sdk/react';

function MyComponent() {
  const showBanner = useFlag('show-banner', false);

  if (!showBanner) return null;
  return <div>New feature!</div>;
}

useFlag(key, defaultValue) returns the server-evaluated value, or defaultValue if the flag doesn't exist or the provider isn't ready yet.

Access client state

import { useFlaggy } from '@getflaggy/sdk/react';

function Status() {
  const { ready, error } = useFlaggy();

  if (error) return <div>Error: {error.message}</div>;
  if (!ready) return <div>Loading...</div>;
  return <div>Flags loaded</div>;
}

Provider props

| Prop | Type | Default | Description | |------|------|---------|-------------| | serverUrl | string | — | Flaggy server URL | | apiKey | string | — | API key | | flags | string[] | — | List of flag keys to evaluate | | context | Record<string, unknown> | {} | Evaluation context (user info, etc.) | | enableStreaming | boolean | true | Enable SSE for real-time flag updates | | onError | (error: Error) => void | — | Error callback (Sentry, Datadog, etc.) |

When context changes (deep comparison), flags are automatically re-evaluated.

Vanilla JavaScript

import { FlaggyClient } from '@getflaggy/sdk';

const client = new FlaggyClient({
  serverUrl: 'https://flaggy.example.com',
  apiKey: 'your-api-key',
  flags: ['show-banner', 'dark-mode'],
  context: { userId: '123' },
});

client.on('ready', () => {
  console.log(client.getFlag('show-banner', false));
});

client.on('change', (key, value) => {
  console.log(`Flag ${key} changed to`, value);
});

client.on('error', (err) => {
  console.error(err);
});

await client.initialize();

// Update context (re-evaluates all flags)
await client.setContext({ userId: '456', plan: 'enterprise' });

// Cleanup
client.destroy();

How it works

1. On init, the SDK calls POST /api/v1/evaluate/batch with the declared flag keys
2. Results are cached locally — getFlag() reads from cache (synchronous)
3. An SSE connection to /api/v1/stream listens for flag changes in real-time
4. On change events, the affected flag is re-evaluated via POST /api/v1/evaluate
5. SSE reconnects automatically with exponential backoff + jitter

License

MIT