Use flags anywhere on the server

The SDK fetches configuration lazily, evaluates locally, and returns your fallback on operational failures. Constructor errors still throw immediately for developer mistakes such as a missing sdk_ key or invalid endpoint.

Global flags

import { flags } from "./superflag"

if (await flags.isEnabled("new-worker")) {
  await runNewWorker()
} else {
  await runCurrentWorker()
}

Without an explicit context, evaluation uses { targetingKey: "server" }. That is appropriate for global flags. A percentage rollout will assign the whole service to one stable cohort.

Per-user or per-organization targeting

const enabled = await flags.isEnabled("new-checkout", {
  targetingKey: organization.id,
  attributes: {
    plan: organization.plan,
    country: organization.country,
  },
})

Use a stable logical identity. Only attributes in the environment privacy allow-list reach the evaluator.

Typed remote configuration

const copy = await flags.getString("checkout-copy", "Continue")
const limit = await flags.getNumber("checkout-limit", 10)
const policy = await flags.getJson("checkout-policy", { mode: "safe" })

You can constrain keys at compile time:

import { createSuperflag } from "@superflag-sh/node"

type Values = {
  "new-checkout": boolean
  "checkout-copy": string
  "checkout-limit": number
}

const flags = createSuperflag<Values>({
  apiKey: process.env.SUPERFLAG_API_KEY!,
})

Evaluation details

const result = await flags.details("new-checkout", false, {
  targetingKey: user.id,
  attributes: { plan: user.plan },
})

logger.info({
  variation: result.details?.variation,
  reason: result.reason,
  configVersion: result.details?.configVersion,
  cacheStatus: result.cacheStatus,
})

Details include evaluation provenance and bounded cache state. They never expose the API key or complete configuration.

Framework pattern

Keep the client outside the request handler:

import { createSuperflag } from "@superflag-sh/node"

const flags = createSuperflag({
  apiKey: process.env.SUPERFLAG_API_KEY!,
  requestTimeoutMs: 1_500,
  maxRetries: 1,
})

export async function POST(request: Request) {
  const session = await authenticate(request)
  const enabled = await flags.isEnabled("new-server-path", {
    targetingKey: session.organizationId,
    attributes: { plan: session.plan },
  })

  return enabled ? newPath(request) : currentPath(request)
}

This works for Next.js route handlers, traditional Node servers, serverless functions, workers, cron jobs, queues, and scripts. The package imports no Node built-ins, filesystem APIs, process hooks, or background intervals.

Refresh and diagnostics

const flags = createSuperflag({
  apiKey: process.env.SUPERFLAG_API_KEY!,
  onDiagnostic(event) {
    observability.emit("superflag", event)
  },
})

await flags.refresh()
const state = flags.getState()

Diagnostics are content-free: no credentials, contexts, evaluated values, or raw configuration. refresh() resolves with state instead of throwing.

Start here

Node and server SDK

React SDK

React Native and Expo

Core SDK

CLI and agents

Feature decisions

HTTP API

Usage

Use flags anywhere on the server

Global flags

Per-user or per-organization targeting

Typed remote configuration

Evaluation details

Framework pattern

Refresh and diagnostics

​Use flags anywhere on the server

​Global flags

​Per-user or per-organization targeting

​Typed remote configuration

​Evaluation details

​Framework pattern

​Refresh and diagnostics

Use flags anywhere on the server

Global flags

Per-user or per-organization targeting

Typed remote configuration

Evaluation details

Framework pattern

Refresh and diagnostics