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
| Option | Package | Updates | Local evaluation | Best for |
|---|---|---|---|---|
@flaggr/sdk, poll mode (default) | @flaggr/sdk | When a cached value expires (10 s by default) | No | Simple remote evaluation, servers |
@flaggr/sdk, batch mode | @flaggr/sdk | Watched and cached flags refreshed every 2 s, up to 100 per request | No | Many flags, few requests |
@flaggr/sdk, stream mode | @flaggr/sdk | Pushed over SSE | Yes | Latency-sensitive apps, live updates |
| React hooks | @flaggr/sdk/react | Follow the client's mode | Follow the client's mode | React and Next.js apps |
| Go and Python SDKs | github.com/flaggr-dev/flaggr-go, flaggr (from GitHub) | Per evaluation | No | Go and Python services |
| OpenFeature OFREP providers | @openfeature/ofrep-provider, and the Python, Go and Java providers | Per evaluation | No | OpenFeature codebases, Java and other languages |
| Standalone evaluator | @flaggr/evaluator | You fetch the configuration | Yes | Edge workers, tests, your own caching |
| REST API | none | Per request | No | Scripts 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' })| Mode | How values arrive | Requests |
|---|---|---|
poll | Each evaluation whose cached value has expired (cacheTtl, 10 s by default) asks the data plane; concurrent evaluations of the same flag share one request | One per flag per cache period |
batch | Every 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 events | One per interval per 100 flags |
stream | The client subscribes to /api/flags/stream, receives the service's flag configurations, and evaluates locally | None 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 overfetchwith the key in theAuthorizationheader. It reconnects with backoff, and if the stream refuses the key (401/403) the client refreshes watched flags everybatchIntervalMsinstead. - The client holds the service's flag configurations, targeting rules included. In a browser, anyone who can read the page can see them; use
pollorbatchwhere 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/sdkinstreammode for live updates and local evaluation, orpollmode to keep targeting rules off the page. - React or Next.js:
@flaggr/sdk/reactin Client Components, andcreateFlaggrin Server Components and route handlers. - Node.js service:
@flaggr/sdkinstreammode (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/evaluatorwith a fetched configuration, or the REST API. - Tests:
@flaggr/evaluatorwith fixture configurations, or@flaggr/sdkwithbootstrap.
Flaggr's data plane also serves Connect-RPC and gRPC; no client for them is published. See Protocols.
Related
- TypeScript SDK — Client options, streaming and telemetry
- Client SDK — Client methods and bootstrap
- React Hooks — React integration
- Protocols — REST, gRPC, Connect, and OFREP protocols