Skip to main content

Choose how your application evaluates Flaggr flags — the TypeScript SDK's update modes, the Go and Python SDKs, OpenFeature OFREP providers, the standalone evaluator, or the REST API

Last updated November 21, 2026

Provider Architecture

Flaggr evaluates a flag either remotely, on the data plane (https://api.flaggr.dev) or the control plane (https://flaggr.dev), or locally, in your process, from the flag's configuration with the data plane's rules. What you install, and how you configure it, decides which. The control plane also applies prerequisites, mutual exclusion groups, experiments and cohorts, which the data plane and local evaluation don't (see Evaluation Flow).

Overview

OptionPackageUpdatesLocal evaluationBest for
@flaggr/sdk, poll mode (default)@flaggr/sdkWhen a cached value expires (10 s by default)NoSimple remote evaluation, servers
@flaggr/sdk, batch mode@flaggr/sdkWatched and cached flags refreshed every 2 s, up to 100 per requestNoMany flags, few requests
@flaggr/sdk, stream mode@flaggr/sdkPushed over SSEYesLatency-sensitive apps, live updates
React hooks@flaggr/sdk/reactFollow the client's modeFollow the client's modeReact and Next.js apps
Go and Python SDKsgithub.com/flaggr-dev/flaggr-go, flaggr (from GitHub)Per evaluationNoGo and Python services
OpenFeature OFREP providers@openfeature/ofrep-provider, and the Python, Go and Java providersPer evaluationNoOpenFeature codebases, Java and other languages
Standalone evaluator@flaggr/evaluatorYou fetch the configurationYesEdge workers, tests, your own caching
REST APInonePer requestNoScripts and one-off calls

For application code, Flaggr publishes @flaggr/sdk and the standalone @flaggr/evaluator it is built on (npm), a Go SDK (on the Go module proxy) and a Python SDK (installed from GitHub; not on PyPI yet). Java and other languages use OpenFeature's OFREP providers.

TypeScript SDK

createFlaggr evaluates remotely by default and can switch to local evaluation with updateMode:

import { createFlaggr } from '@flaggr/sdk'
 
const client = createFlaggr({
  serviceId: 'web-app',
  apiKey: 'fgr_your_token',
  environment: 'production',
  updateMode: 'stream', // 'poll' (default) | 'batch' | 'stream'
})
 
const enabled = await client.getBooleanValue('checkout-v2', false, { targetingKey: 'user-123' })
ModeHow values arriveRequests
pollEach evaluation whose cached value has expired (cacheTtl, 10 s by default) asks the data plane; concurrent evaluations of the same flag share one requestOne per flag per cache period
batchEvery batchIntervalMs (2 s by default), the client refreshes every flag it has cached or that you watch with onFlagChange or a React hook, and changed values fire change eventsOne per interval per 100 flags
streamThe client subscribes to /api/flags/stream, receives the service's flag configurations, and evaluates locallyNone per evaluation

Switch at run time with client.setUpdateMode('batch'); the client tears down the old transport before starting the new one.

In stream mode:

  • Flags whose rules use operators the data plane doesn't implement (exists, not_exists, in_cohort, not_in_cohort) are still evaluated remotely.
  • With an apiKey, the stream runs over fetch with the key in the Authorization header. It reconnects with backoff, and if the stream refuses the key (401/403) the client refreshes watched flags every batchIntervalMs instead.
  • The client holds the service's flag configurations, targeting rules included. In a browser, anyone who can read the page can see them; use poll or batch where the rules must stay on the server.

Server-rendered pages

To evaluate on first render without a request, pass flag configurations with the bootstrap option, or let remoteConfig: true fetch them from the control plane. See Bootstrap (SSR).

React

FlaggrProvider creates a client with the same options, and the hooks re-render when values change. See React Hooks, including Next.js App Router setup.

Go and Python SDKs

Flaggr's Go SDK and Python SDK evaluate each flag remotely: one POST /api/flags/evaluate request per evaluation, with no cache. Both evaluate in production unless you choose another environment. The Python SDK sends evaluations to the data plane by default; the Go SDK sends them to https://flaggr.dev unless you set WithAPIURL("https://api.flaggr.dev"). The Go SDK can also answer boolean and string flags from an in-process cache that you fill, applying only on/off state, default values and overrides.

OpenFeature (OFREP)

Any OpenFeature SDK with an OFREP provider evaluates Flaggr flags through Flaggr's OFREP endpoint. This is how Java services use Flaggr, and how code that already uses OpenFeature can, in TypeScript, Python, Go or another language:

import { OpenFeature } from '@openfeature/server-sdk'
import { OFREPProvider } from '@openfeature/ofrep-provider'
 
await OpenFeature.setProviderAndWait(new OFREPProvider({
  baseUrl: 'https://api.flaggr.dev/api',
  headers: [
    ['Authorization', `Bearer ${process.env.FLAGGR_TOKEN}`],
    ['X-Service-Id', 'api-server'],
    ['X-Environment', 'production'],
  ],
}))
 
const client = OpenFeature.getClient()
const enabled = await client.getBooleanValue('checkout-v2', false, { targetingKey: 'user-123' })

Each evaluation is one request. Without X-Environment, OFREP evaluates in development.

Standalone Evaluator

@flaggr/evaluator evaluates a flag configuration in-process with the same rules as the data plane. It has no dependencies and needs no Node.js APIs, so it runs in edge runtimes:

import { evaluateFlag } from '@flaggr/evaluator'
 
const res = await fetch(
  'https://api.flaggr.dev/api/flags/export?serviceId=edge-app&environment=production',
  { headers: { Authorization: `Bearer ${FLAGGR_TOKEN}` } },
)
const { flags } = await res.json()
 
const result = evaluateFlag(flags['checkout-v2'], { targetingKey: 'user-123', plan: 'enterprise' })
// { value: true, reason: 'TARGETING_MATCH' }

You decide when to fetch the configuration again. isLocallyEvaluable (0.3.0 and later) tells you whether a flag uses only the operators the data plane implements. See Edge & Serverless.

REST API

POST /api/flags/evaluate and POST /api/flags/evaluate/batch on https://api.flaggr.dev evaluate without an SDK. See Quick Start and the REST API reference.

Choosing

  • Browser app or SPA: @flaggr/sdk in stream mode for live updates and local evaluation, or poll mode to keep targeting rules off the page.
  • React or Next.js: @flaggr/sdk/react in Client Components, and createFlaggr in Server Components and route handlers.
  • Node.js service: @flaggr/sdk in stream mode (local evaluation), or an OFREP provider if your code already uses OpenFeature.
  • Go or Python: Flaggr's Go or Python SDK, or the OpenFeature OFREP provider if your code already uses OpenFeature.
  • Java: the OpenFeature OFREP provider.
  • Edge functions and workers: @flaggr/evaluator with a fetched configuration, or the REST API.
  • Tests: @flaggr/evaluator with fixture configurations, or @flaggr/sdk with bootstrap.

Flaggr's data plane also serves Connect-RPC and gRPC; no client for them is published. See Protocols.