@getflipflag/sdk

The official JavaScript SDK for FlipFlag — evaluate feature flags in your frontend app with one function call.

What is this?

FlipFlag lets you turn features on/off for your users without redeploying your app. This SDK connects your frontend to the FlipFlag backend and tells you which flags are enabled for a given user.

Installation

npm install @getflipflag/sdk

Quick Start

import flipflag from "@getflipflag/sdk"

// 1. Initialize once at app startup (fetches all flags from FlipFlag backend)
await flipflag.init({
  sdkKey: "ff_dev_xxxxxxxx",  // get this from FlipFlag dashboard → Settings → Developer
  baseURL: "https://flipflag.onrender.com",
})

// 2. Check flags anywhere in your app (instant, no network call)
if (flipflag.isEnabled("new-checkout")) {
  // show new checkout flow
} else {
  // show old checkout flow
}

Usage with User Targeting

Pass a user context to evaluate flags per user — useful for targeting specific users or plans:

await flipflag.init({
  sdkKey: "ff_dev_xxxxxxxx",
  baseURL: "https://flipflag.onrender.com",
  userContext: {
    userId: "user-123",               // used for percentage rollouts
    attributes: { plan: "premium" },  // used for rule-based targeting
  },
})

flipflag.isEnabled("beta-feature")  // → true or false based on targeting rules

Usage with React

import { useState, useEffect } from "react"
import flipflag from "@getflipflag/sdk"

export default function App() {
  const [flags, setFlags] = useState(null)

  useEffect(() => {
    flipflag.init({
      sdkKey: import.meta.env.VITE_FLIPFLAG_SDK_KEY,
      baseURL: import.meta.env.VITE_FLIPFLAG_BASE_URL,
      userContext: { userId: "user-123", attributes: { plan: "pro" } },
    }).then(() => {
      setFlags(flipflag.allFlags())
    })
  }, [])

  if (!flags) return <div>Loading...</div>

  return (
    <div>
      {flags["new-hero"] ? <NewHero /> : <OldHero />}
    </div>
  )
}

API Reference

flipflag.init(config) → Promise<void>

Fetches all flags from the FlipFlag backend. Call this once at app startup.

| Option | Type | Required | Default | Description | |---|---|---|---|---| | sdkKey | string | ✅ | — | SDK key from FlipFlag dashboard | | baseURL | string | ❌ | http://localhost:3001 | Your FlipFlag backend URL | | userContext | object | ❌ | {} | User info for targeting | | timeout | number | ❌ | 5000 | Request timeout in ms | | onError | function | ❌ | null | Called if the fetch fails |

flipflag.isEnabled(key, fallback?) → boolean

Check if a flag is enabled. Reads from cache — no network call.

flipflag.isEnabled("new-checkout")        // → false (default fallback)
flipflag.isEnabled("new-checkout", true)  // → true (custom fallback if flag missing)

flipflag.allFlags() → object

Returns all flags as a plain object.

flipflag.allFlags()  // → { "new-checkout": true, "beta-ui": false }

flipflag.isReady() → boolean

Returns true after a successful init().

if (flipflag.isReady()) {
  // safe to call isEnabled()
}

flipflag.identify(userContext) → Promise<void>

Update the user context and re-fetch flags. Use this after login or a plan upgrade.

// User just logged in
await flipflag.identify({
  userId: "user-456",
  attributes: { plan: "premium" },
})

flipflag.refresh() → Promise<void>

Re-fetch flags from the backend without changing the user context.

await flipflag.refresh()

flipflag.startPolling(interval?) → void

Auto-refresh flags every N milliseconds. Flags update in the background — no page refresh needed.

flipflag.startPolling(5000)   // re-fetch every 5 seconds
flipflag.startPolling(30000)  // re-fetch every 30 seconds (default)

flipflag.stopPolling() → void

Stop the auto-refresh.

flipflag.stopPolling()

flipflag.onChange(cb) → () => void

Register a callback that fires whenever flags are updated (after every successful fetch or poll). Returns an unsubscribe function.

const unsub = flipflag.onChange((flags) => {
  console.log("Flags updated:", flags)
})

// Later, to stop listening:
unsub()

React example — re-render automatically when flags change:

useEffect(() => {
  flipflag.init({ sdkKey: "...", baseURL: "..." }).then(() => {
    setFlags(flipflag.allFlags())
    flipflag.startPolling(5000)
  })

  const unsub = flipflag.onChange((updatedFlags) => setFlags({ ...updatedFlags }))

  return () => {
    unsub()
    flipflag.stopPolling()
  }
}, [])

How It Works

1. init() makes a single POST request to your FlipFlag backend with the user context
2. The backend evaluates all flags for that user and returns { "flag-key": true/false }
3. The SDK caches the result — every isEnabled() call after that reads from cache instantly
4. No continuous polling — call refresh() manually if you need updated values

Your App
  ↓
flipflag.init()  →  POST /api/sdk/flags  →  FlipFlag Backend
                                                  ↓
                                          evaluate flags for user
                                                  ↓
                ←  { "new-checkout": true }  ←───
  ↓
flipflag.isEnabled("new-checkout")  →  true  (instant, from cache)

Error Handling

Errors never throw to your app — they're caught internally and passed to onError:

await flipflag.init({
  sdkKey: "ff_dev_xxx",
  onError: (err) => {
    console.error("FlipFlag failed:", err.message)
    // app continues with fallback values
  },
})

If init() fails, isReady() returns false and isEnabled() returns the fallback value (default: false).

TypeScript

Types are included out of the box — no @types package needed.

import flipflag from "@getflipflag/sdk"
// fully typed ✅

License

MIT