@superflag-sh/node

Portable server-side feature flags for Node.js, Bun, Deno, Next.js, Vercel, Cloudflare Workers, and other runtimes with standard fetch and AbortController APIs.

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

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

if (await flags.isEnabled("new-checkout")) {
  // New server behavior
}

Use an environment-scoped sdk_ server key. Never expose this key through an EXPO_PUBLIC_*, NEXT_PUBLIC_*, browser bundle, mobile app, or client response.

API

await flags.isEnabled("boolean-flag"); // safe fallback: false
await flags.getString("copy", "Default copy");
await flags.getNumber("limit", 10);
await flags.getJson("policy", { mode: "safe" });

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

await flags.refresh();
flags.getState();

Reads lazily fetch the server configuration, coalesce concurrent first reads, evaluate locally through @superflag-sh/core, and return their fallback on network, authorization, schema, or evaluation failures. Reads do not throw. Constructor validation does throw for developer mistakes such as a missing sdk_ key or invalid endpoint.

endpoint and an injected fetch are credential-bearing interfaces: both receive the complete sdk_ bearer key. They must be fixed trusted infrastructure, never request- or user-controlled, and must not log, persist, or forward authorization headers. A custom fetch must pass init.signal to its underlying request; otherwise requestTimeoutMs cannot abort in-flight work. Custom endpoints require HTTPS. A loopback HTTP endpoint can be enabled only for local development:

const localFlags = createSuperflag({
  apiKey: process.env.SUPERFLAG_API_KEY!,
  endpoint: "http://127.0.0.1:3000/api/v1/advanced-config",
  allowInsecureHttpForLocalDevelopment: true,
});

The client keeps an in-memory, endpoint/key/source-bound last-known-good config. It honors the server TTL and ETag, revalidates stale data in the background, and bounds stale fallback with maxStaleAgeSeconds. A 401 or 403 clears the cache immediately. A 429 honors a bounded Retry-After or applies a safe default backoff when the header is absent. Public values, details, diagnostics, and state are detached from the internal cache. No key, context, or raw configuration is persisted.

Targeting contexts

Context is optional for a global flag. A missing context uses the stable { targetingKey: "server" } subject so the zero-boilerplate example works. That means a percentage rollout without an explicit context assigns the entire service instance to one cohort. Pass a request identity when you need per-user, per-organization, or per-request targeting:

await flags.isEnabled("new-checkout", {
  targetingKey: organization.id,
  attributes: { plan: organization.plan },
});

Superflag's environment privacy allow-list is applied before local evaluation; attributes not explicitly allowed by the server are discarded.

Serverless and edge runtimes

Create one client at module scope. The package has no filesystem dependency, background interval, process hook, or Node built-in import. It uses only request-scoped timers for timeouts/retries and accepts an injected fetch for tests or custom runtimes.

const flags = createSuperflag({
  apiKey: env.SUPERFLAG_API_KEY,
  requestTimeoutMs: 1_500,
  maxRetries: 1,
  onDiagnostic(event) {
    observability.emit("superflag", event);
  },
});

Diagnostics contain bounded operational metadata only. They never contain the API key, evaluation context, flag value, or complete configuration.

Core package distinction

@superflag-sh/core/node is a pure helper for callers that already possess a config. This package, @superflag-sh/node, is the networked server SDK: it owns authenticated config sync, TTL/ETag caching, failure policy, and diagnostics, then delegates all evaluation semantics to core.