> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Evaluate flags in Node, serverless functions, API routes, jobs, and edge runtimes

# 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

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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

```ts theme={null}
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:

```ts theme={null}
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

```ts theme={null}
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.