Evaluate Flaggr flags in Cloudflare Workers, Vercel Edge Functions, Deno and serverless functions with @flaggr/evaluator or @flaggr/sdk
Last updated November 14, 2026
Edge & Serverless
In edge runtimes and short-lived functions, cold starts and bundle size matter, and connections don't survive from one invocation to the next. Two published packages fit:
| Package | Dependencies | Network | Best for |
|---|---|---|---|
@flaggr/evaluator | None | You fetch the flag configuration and decide when to fetch it again | Cloudflare Workers, Vercel Edge Functions, Deno |
@flaggr/sdk in poll mode | @flaggr/evaluator | One request per flag whenever its cached value (10 s by default) has expired | Node.js serverless functions |
Standalone Evaluator
@flaggr/evaluator evaluates a flag configuration in-process with the same rules as Flaggr's data plane. It has no dependencies and needs no Node.js APIs.
npm install @flaggr/evaluatorFetch the service's configuration from the data plane, then evaluate locally:
import { evaluateFlag, type FlagConfig } from '@flaggr/evaluator'
const response = await fetch(
'https://api.flaggr.dev/api/flags/export?serviceId=edge-app&environment=production',
{ headers: { Authorization: 'Bearer fgr_your_token' } },
)
const { flags } = (await response.json()) as { flags: Record<string, FlagConfig> }
const flag = flags['checkout-v2']
const result = flag
? evaluateFlag(flag, { targetingKey: 'user-123', plan: 'enterprise' })
: { value: false, reason: 'NOT_FOUND' }GET /api/flags/export returns { flags, serviceId, environment, generatedAt }, with flags keyed by flag key. It needs a project API token that can read the service, and exports production when you don't name an environment. evaluateFlag returns { value, reason, variant }; it has no default value of its own, so check that the flag exists first.
The data plane doesn't implement the exists, not_exists, in_cohort and not_in_cohort operators, so a flag that uses them can evaluate differently in-process. From @flaggr/evaluator 0.3.0, isLocallyEvaluable(flag) returns false for such a flag: evaluate it with POST /api/flags/evaluate instead.
Cloudflare Workers Example
Cache the configuration in Workers KV so most requests make no call to Flaggr:
import { evaluateFlag, type FlagConfig } from '@flaggr/evaluator'
interface Env {
FLAGGR_TOKEN: string
FLAGS_KV: KVNamespace
}
async function loadFlags(env: Env): Promise<Record<string, FlagConfig>> {
const cached = await env.FLAGS_KV.get<Record<string, FlagConfig>>('flaggr:flags', 'json')
if (cached) return cached
const response = await fetch(
'https://api.flaggr.dev/api/flags/export?serviceId=edge-app&environment=production',
{ headers: { Authorization: `Bearer ${env.FLAGGR_TOKEN}` } },
)
if (!response.ok) return {}
const { flags } = (await response.json()) as { flags: Record<string, FlagConfig> }
await env.FLAGS_KV.put('flaggr:flags', JSON.stringify(flags), { expirationTtl: 60 })
return flags
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const flags = await loadFlags(env)
const userId = request.headers.get('x-user-id') ?? 'anonymous'
const flag = flags['new-ui']
const showNewUI = flag ? evaluateFlag(flag, { targetingKey: userId }).value === true : false
return showNewUI ? renderNewUI(request) : renderClassicUI(request)
},
}A flag change reaches the Worker when the cached copy expires (60 seconds here, the shortest time KV allows).
Vercel Edge Functions
Module-scope variables survive between warm invocations, so keep the configuration there and fetch it again after a while:
import { evaluateFlag, type FlagConfig } from '@flaggr/evaluator'
export const runtime = 'edge'
let flags: Record<string, FlagConfig> | null = null
let fetchedAt = 0
async function getFlags(): Promise<Record<string, FlagConfig>> {
if (flags && Date.now() - fetchedAt < 30_000) return flags
const response = await fetch(
`https://api.flaggr.dev/api/flags/export?serviceId=${process.env.FLAGGR_SERVICE_ID}&environment=production`,
{ headers: { Authorization: `Bearer ${process.env.FLAGGR_TOKEN}` }, cache: 'no-store' },
)
if (response.ok) {
flags = ((await response.json()) as { flags: Record<string, FlagConfig> }).flags
fetchedAt = Date.now()
}
return flags ?? {}
}
export async function GET() {
const flag = (await getFlags())['show-banner']
const showBanner = flag ? evaluateFlag(flag, { targetingKey: 'anonymous' }).value : false
return Response.json({ showBanner })
}Serverless Functions (Node.js)
In Node.js functions, @flaggr/sdk in its default poll mode evaluates remotely and keeps nothing open between invocations. Create the client at module scope so warm invocations reuse its cache:
import { createFlaggr } from '@flaggr/sdk'
const flaggr = createFlaggr({
serviceId: process.env.FLAGGR_SERVICE_ID!,
apiKey: process.env.FLAGGR_TOKEN,
environment: 'production',
})
export async function handler(event: { userId: string }) {
const enabled = await flaggr.getBooleanValue('new-pricing', false, { targetingKey: event.userId })
return { statusCode: 200, body: JSON.stringify({ enabled }) }
}Avoid stream and batch mode in functions: they keep a connection or a timer running, which a frozen function can't.
Create the client, or load the configuration, outside the handler so it persists across warm invocations. Only a cold start pays for the first fetch.
Bundled Configuration
For flags that change only with a deploy, save the export at build time and bundle it with your code. Evaluating it makes no network calls at all:
import { evaluateFlag, type FlagConfig } from '@flaggr/evaluator'
import exported from './flags.json' // saved from GET /api/flags/export at build time
const flags = exported.flags as Record<string, FlagConfig>A change made in Flaggr reaches these flags only with your next build.
Related
- Provider Architecture — All the ways to evaluate flags
- Caching Strategy — Cache tiers and TTLs
- Performance — Choosing the fastest path