SDK Overview

The @switchflag/sdk package is the official TypeScript SDK for evaluating feature flags. It ships two variants through separate export paths.

Standard SDK

Import from @switchflag/sdk.

Best for long-lived server processes (Node.js servers, background workers). Uses an in-memory Map cache — the first call for a flag key fetches from the API, and subsequent calls return from cache with no network overhead.

import { createClient } from '@switchflag/sdk'

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

const result = await client.getFlag<boolean>('dark-mode', {
  userId: 'user-123',
})

Edge SDK

Import from @switchflag/sdk/edge.

Designed for ephemeral edge runtimes (Vercel Edge Functions, Cloudflare Workers, Next.js Middleware). Uses fetch with cache: 'force-cache' and a 60-second revalidation window, delegating caching to the edge network.

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

const result = await evaluateAtEdge<boolean>(
  { apiKey: process.env.SWITCHFLAG_API_KEY! },
  'dark-mode',
  { userId: 'user-123' },
)

How evaluation works

Both variants follow the same flow:

1. Fetch the flag configuration from GET /v1/flags/{key} (with caching)
2. Run the evaluation engine locally — check if the flag is enabled, evaluate targeting rules in order, return the first match or the default value
3. Return an EvaluationResult with the resolved value, reason, and matching rule ID

The evaluation engine runs client-side. There's no server round-trip per getFlag call — the SDK fetches the flag config once and evaluates locally.

Pages

• Installation — install and requirements
• Client — createClient() reference
• getFlag — getFlag() reference
• Edge — evaluateAtEdge() reference
• Types — all exported TypeScript types