Connect the SDK

Install the Switchflag SDK, initialize a client, and evaluate your first feature flag.

Install

npm install @switchflag/sdk

The SDK requires Node.js 18+ and ships as ESM only.

Option 1: Client instance

Create a client instance for full control over configuration and caching.

import { createClient } from '@switchflag/sdk'

const client = createClient({
  apiKey: 'sf_development_...', // your environment API key
})

const result = await client.getFlag<boolean>('new-checkout-flow', {
  userId: 'user-123',
  email: 'jane@acme.com',
  country: 'US',
})

if (result.value) {
  // new checkout flow
} else {
  // original checkout flow
}

The client uses an in-memory Map cache. The first call to getFlag for a given key fetches the flag configuration from the API. Subsequent calls return from cache instantly.

Option 2: Singleton

For simpler setups, use the singleton pattern. Call init() once at startup, then use getFlag() anywhere.

// app startup
import { init } from '@switchflag/sdk'
init('sf_development_...')

// anywhere in your app
import { getFlag } from '@switchflag/sdk'

const result = await getFlag<boolean>('new-checkout-flow', {
  userId: 'user-123',
})

Evaluation context

The second argument to getFlag is the evaluation context — an object with attributes about the current user or request. The SDK uses this to evaluate targeting rules.

interface EvaluationContext {
  userId?: string
  email?: string
  country?: string
  [key: string]: unknown // any custom attributes
}

Built-in fields (userId, email, country) are optional. You can pass any additional properties for use in targeting rules.

Evaluation result

Every call to getFlag returns an EvaluationResult:

interface EvaluationResult<T> {
  value: T          // the resolved flag value
  reason: string    // why this value was chosen
  ruleId?: string   // which rule matched (if any)
}

The reason field tells you how the value was determined:

Reason	Description
`default`	Flag is enabled, no rules matched, returned the default value
`rule_match`	A targeting rule matched
`disabled`	Flag is disabled in this environment
`not_found`	Flag key doesn't exist or API returned an error

Edge SDK

For edge runtimes (Vercel Edge Functions, Cloudflare Workers, Next.js Middleware), use the edge import:

import { evaluateAtEdge } from '@switchflag/sdk/edge'

const result = await evaluateAtEdge<boolean>(
  { apiKey: 'sf_production_...' },
  'new-checkout-flow',
  { userId: 'user-123' },
)

The edge SDK uses fetch with cache: 'force-cache' and a 60-second revalidation window, delegating caching to the edge network since edge functions are ephemeral.

Full example: Next.js server component

import { createClient } from '@switchflag/sdk'

const client = createClient({
  apiKey: process.env.SWITCHFLAG_API_KEY!,
})

export default async function PricingPage() {
  const { value: showNewPricing } = await client.getFlag<boolean>(
    'new-pricing-page',
    { userId: 'anonymous' },
  )

  return showNewPricing ? <NewPricing /> : <CurrentPricing />
}

Full example: Next.js middleware (edge)

import { evaluateAtEdge } from '@switchflag/sdk/edge'
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  const userId = request.cookies.get('userId')?.value ?? 'anonymous'

  const { value: maintenanceMode } = await evaluateAtEdge<boolean>(
    { apiKey: process.env.SWITCHFLAG_API_KEY! },
    'maintenance-mode',
    { userId },
  )

  if (maintenanceMode) {
    return NextResponse.rewrite(new URL('/maintenance', request.url))
  }

  return NextResponse.next()
}

Next steps

SDK Reference — full API reference for createClient, getFlag, and evaluateAtEdge
Evaluation Engine — how targeting rules and percentage rollouts work
API Reference — REST API for direct integrations without the SDK

On this page