JavaScript SDK

The Flipswitch JavaScript SDK provides an OpenFeature-compatible provider with automatic cache invalidation via Server-Sent Events (SSE).

Installation

npm install @flipswitch/sdk @openfeature/web-sdk

For server-side (Node.js), use @openfeature/server-sdk instead:

npm install @flipswitch/sdk @openfeature/server-sdk

Quick Start

Browser (React, Vue, etc.)

import { FlipswitchProvider } from '@flipswitch/sdk';
import { OpenFeature } from '@openfeature/web-sdk';
 
// Only API key is required
const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY'
});
 
// Register with OpenFeature
await OpenFeature.setProviderAndWait(provider);
 
// Get a client and evaluate flags
const client = OpenFeature.getClient();
const darkMode = await client.getBooleanValue('dark-mode', false);
const welcomeMessage = await client.getStringValue('welcome-message', 'Hello!');

Node.js (Server)

import { FlipswitchProvider } from '@flipswitch/sdk';
import { OpenFeature } from '@openfeature/server-sdk';
 
const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY'
});
 
await OpenFeature.setProviderAndWait(provider);
const client = OpenFeature.getClient();
 
// Evaluate with context
const context = {
  targetingKey: 'user-123',
  email: 'user@example.com',
  plan: 'premium',
};
 
const showFeature = await client.getBooleanValue('new-feature', false, context);

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	required	Environment API key from dashboard
`baseUrl`	`string`	`https://api.flipswitch.dev`	Your Flipswitch server URL
`enableRealtime`	`boolean`	`true`	Enable SSE for real-time flag updates
`pollingInterval`	`number`	`30000`	Cache TTL in milliseconds
`fetchImplementation`	`typeof fetch`	`fetch`	Custom fetch function

const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.flipswitch.dev',
  enableRealtime: true,
  pollingInterval: 30000,
});

Real-Time Updates

When enableRealtime is enabled (default), the SDK maintains an SSE connection to receive instant flag changes:

The SSE client receives a flag-change event
The local cache is immediately invalidated
Next flag evaluation fetches the fresh value
OpenFeature emits a PROVIDER_CONFIGURATION_CHANGED event

Event Handlers

const provider = new FlipswitchProvider(
  { apiKey: 'YOUR_API_KEY' },
  {
    onFlagChange: (event) => {
      console.log(`Flag changed: ${event.flagKey}`);
    },
    onConnectionStatusChange: (status) => {
      console.log(`SSE status: ${status}`);
    },
  }
);

Connection Status

// Check current SSE status
const status = provider.getSseStatus();
// 'connecting' | 'connected' | 'disconnected' | 'error'
 
// Force reconnect
provider.reconnectSse();

React Integration

import { OpenFeature, OpenFeatureProvider, useFlag } from '@openfeature/react-sdk';
import { FlipswitchProvider } from '@flipswitch/sdk';
 
// Initialize provider (do this once at app startup)
const provider = new FlipswitchProvider({
  apiKey: 'YOUR_API_KEY',
});
 
await OpenFeature.setProviderAndWait(provider);
 
function App() {
  return (
    <OpenFeatureProvider>
      <MyComponent />
    </OpenFeatureProvider>
  );
}
 
function MyComponent() {
  const { value: darkMode } = useFlag('dark-mode', false);
 
  return (
    <div className={darkMode ? 'dark' : 'light'}>
      Dark mode is {darkMode ? 'enabled' : 'disabled'}
    </div>
  );
}

The useFlag hook automatically re-renders when flags change via SSE.

Evaluation Context

Pass user attributes for targeting:

const context = {
  targetingKey: 'user-123',      // Required: unique user identifier
  email: 'user@example.com',
  plan: 'premium',
  country: 'SE',
  version: '2.1.0',
};
 
const showFeature = await client.getBooleanValue('feature', false, context);

Bulk Flag Evaluation

Evaluate all flags at once or get detailed evaluation results:

// Evaluate all flags
const flags = await provider.evaluateAllFlags(context);
for (const flag of flags) {
  console.log(`${flag.key} (${flag.valueType}): ${flag.value}`);
}
 
// Evaluate a single flag with full details
const flag = await provider.evaluateFlag('dark-mode', context);
if (flag) {
  console.log(`Value: ${flag.value}, Reason: ${flag.reason}, Variant: ${flag.variant}`);
}

Reconnection Strategy

The SSE client automatically reconnects with exponential backoff:

Initial delay: 1 second
Maximum delay: 30 seconds
Backoff multiplier: 2x

When reconnected, the provider status changes from STALE back to READY.

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type { FlipswitchProvider, FlipswitchConfig, SseStatus } from '@flipswitch/sdk';

Troubleshooting

SSE connection keeps disconnecting

Check if your server or proxy supports long-lived connections. Some proxies timeout after 30-60 seconds.

Flags not updating in real-time

Verify that enableRealtime is true (default) and check the SSE status:

console.log(provider.getSseStatus());

CORS errors

Ensure your Flipswitch server has CORS configured to allow requests from your domain.

JavaScript SDK

On this page