JavaScript / TypeScript SDK

The official JavaScript/TypeScript SDK for Flagpool. Evaluate feature flags locally with zero server round-trips, deterministic rollouts, and real-time updates.

Installation

npm install @flagpool/sdk

Quick Start

import { FlagpoolClient } from '@flagpool/sdk'

const client = new FlagpoolClient({
  projectId: 'your-project-uuid',
  apiKey: 'your-api-key',
  decryptionKey: 'your-decryption-key',
  context: {
    userId: 'user-123',
    email: 'alice@example.com',
    plan: 'pro',
  },
})

await client.init()

// Boolean flag
if (client.isEnabled('new-dashboard')) {
  showNewDashboard()
}

// String, number, or JSON flag
const buttonColor = client.getValue('cta-button-color')

// Clean up when done
client.close()

Configuration

const client = new FlagpoolClient({
  // Required
  projectId: 'your-project-uuid',
  apiKey: 'your-api-key',
  decryptionKey: 'your-decryption-key',

  // Optional
  context: {
    userId: 'user-123',
    email: 'user@example.com',
    plan: 'pro',
  },
  pollingInterval: 30000, // Auto-refresh interval in ms (default: 30000)
  urlOverride: undefined, // Complete URL override (for self-hosted/testing)
  analytics: {
    enabled: true, // Enable evaluation analytics (default: false)
  },
})

Option	Type	Required	Description
projectId	string	Yes	Project UUID from the dashboard
apiKey	string	Yes	Environment-specific API key
decryptionKey	string	Yes	For CDN URL hashing and target list decryption
context	object	No	User context for targeting rules
pollingInterval	number	No	Polling interval in ms (default: 30000)
urlOverride	string	No	Complete URL override for self-hosted setups
analytics	object	No	Analytics configuration (opt-in)

API Reference

Method	Description
init()	Initialize client and fetch flags (required before evaluation)
isEnabled(key, defaultValue?)	Check if a boolean flag is enabled
getValue(key)	Get flag value (any type)
getVariation(key)	Alias for getValue
getAllFlags()	Get all evaluated flag values as an object
updateContext(ctx)	Update user context — flags re-evaluate automatically
onChange(callback)	Subscribe to flag value changes; returns an unsubscribe function
close()	Stop polling and flush analytics

Flag Types

Boolean Flags

if (client.isEnabled('feature-flag')) {
  // Feature is enabled for this user
}

String Flags

Perfect for A/B tests and feature variants:

const variant = client.getValue('button-color')
// 'blue' | 'green' | 'orange'

Number Flags

Great for limits, thresholds, and configurations:

const limit = client.getValue('rate-limit')
// 100 | 1000 | 10000

JSON Flags

For complex configurations:

const config = client.getValue('checkout-config')
// { showCoupons: true, maxItems: 50, paymentMethods: [...] }

Dynamic Context Updates

Update user context on the fly — flags re-evaluate automatically:

// User on free plan
console.log(client.getValue('max-upload-size-mb')) // 10

// User upgrades to pro
client.updateContext({ plan: 'pro' })

// Instantly gets pro limits
console.log(client.getValue('max-upload-size-mb')) // 100

Real-Time Updates

Flags automatically refresh in the background via polling. Listen for changes:

client.onChange((flagKey, newValue) => {
  console.log(`Flag ${flagKey} changed to:`, newValue)

  if (flagKey === 'maintenance-mode' && newValue === true) {
    showMaintenanceBanner()
  }
})

Offline Support

The SDK caches flags locally. If the network is unavailable during initialization, it falls back to cached values from the last successful fetch:

await client.init() // Uses cache if network fails

const feature = client.isEnabled('my-feature') // Always returns a value

Framework Examples

Node.js / Express

import { FlagpoolClient } from '@flagpool/sdk'
import express from 'express'

const app = express()

const flagpool = new FlagpoolClient({
  projectId: process.env.FLAGPOOL_PROJECT_ID!,
  apiKey: process.env.FLAGPOOL_API_KEY!,
  decryptionKey: process.env.FLAGPOOL_DECRYPTION_KEY!,
})

await flagpool.init()

app.get('/api/data', (req, res) => {
  flagpool.updateContext({ userId: req.user.id })

  if (flagpool.isEnabled('new-api-response')) {
    return res.json({ version: 'v2', data: newData })
  }
  return res.json({ version: 'v1', data: legacyData })
})

Next.js (Server-Side)

import { FlagpoolClient } from '@flagpool/sdk'

let client: FlagpoolClient | null = null

export async function getFlags(userId: string) {
  if (!client) {
    client = new FlagpoolClient({
      projectId: process.env.FLAGPOOL_PROJECT_ID!,
      apiKey: process.env.FLAGPOOL_API_KEY!,
      decryptionKey: process.env.FLAGPOOL_DECRYPTION_KEY!,
      context: { userId },
    })
    await client.init()
  }

  return {
    newDashboard: client.isEnabled('new-dashboard'),
    buttonColor: client.getValue('button-color'),
  }
}

For client-side React/Next.js usage, see the React SDK.

Analytics

Track flag evaluation counts. Analytics is opt-in and disabled by default.

const client = new FlagpoolClient({
  // ...required options
  analytics: {
    enabled: true,
    flushInterval: 60000, // Flush interval in ms (min: 30000)
    flushThreshold: 100, // Flush after N evaluations
    sampleRate: 1.0, // Sample rate (0.0–1.0)
  },
})

Option	Type	Default	Description
enabled	boolean	false	Enable/disable analytics
flushInterval	number	60000	Flush interval in ms (minimum: 30000)
flushThreshold	number	100	Flush after N evaluations
sampleRate	number	1.0	Sample rate (0.0–1.0)

Debugging in the Browser

// Inspect state in the browser console
console.log(__FLAGPOOL__.state.analytics)
console.log(__FLAGPOOL__.state.flags)

// Force flush
__FLAGPOOL__.flushAnalytics()

Targeting Operators

Operator	Description	Example
eq	Equals	plan == "enterprise"
neq	Not equals	plan != "free"
in	In list	country in ["US", "CA"]
nin	Not in list	country not in ["CN", "RU"]
contains	String contains	email contains "@company.com"
startsWith	String starts with	userId startsWith "admin-"
inTargetList	In target list	userId in beta-testers
notInTargetList	Not in target list	userId not in blocked-users

Next Steps

• React SDK — if you're building a React or Next.js frontend
• Getting Started — full setup guide