Skip to main content
@fireweaveai/web-sdk is the Fireweave browser binding. It evaluates control points synchronously from a prefetched cache and registers targets via registerTarget / identify. Those are the two v1 capabilities. The wire protocol still uses flagKey. This is a different surface from @fireweaveai/server-sdk. It is not a Node, Bun, or Deno server target.
Authenticate the web SDK with a fw_public_ key scoped to flags:evaluate and events:write. Do not embed a secret or attest:write project key in a frontend bundle. Key families and issuance: Configuration.

Supported runtime

It ships no server entry point, reads no environment, and imports no runtime built-ins.

Install

or bun add @fireweaveai/web-sdk.

Initialize

initFireweave is the single entry point. mode is required and never inferred. Reads after init are synchronous.
Local mode (no network, no credentials):
A bad host or missing credential still throws at initFireweave(). FireweaveWebRuntime.initialize() itself is fail-open: a hung prefetch must not block app boot. When the initial prefetch loses its 5 second race (DEFAULT_FLAGS_READY_TIMEOUT_MS), the runtime serves defaults with reason STALE.

Lifecycle and STALE

States include STALE: prefetch raced the 5 second ceiling and lost. Reads are defaults with reason STALE. Collapsing STALE into READY would make a timed-out boot indistinguishable from a successful one where every control point is off.

Configuration and authentication

apiUrl and apiKey are required in remote mode. The package reads no environment.
Use a fw_public_ key. The adapter rejects phc_ / phs_ / phx_ shapes (assertNotSecretKey) with Configuration. Default allowlist: app-server.fireweave.ai, staging-app-server.fireweave.ai, loopback. https off-loopback; http on loopback only. Auth: Authorization: Bearer <key>. Paths: /v1/flags/evaluate, /v1/targets/register. See Configuration and auth.

Targets: registerTarget and identify

Web exposes both. registerTarget matches the other languages. identify is the sign-in helper: it registers, then setContext({ targetingKey }) so the next prefetch buckets on that id.
identify is not OpenFeature identify and not analytics identify. Options: kind?: 'user' | 'device', properties?, environment?. See Targeting and targets.

Control points (synchronous)

ExpectedFlagType: 'boolean' | 'string' | 'number' | 'object' — same IEEE-754 number model as Node.
Nine methods, all sync. Evaluation never throws. client.flags is the same object as client.controlPoints (deprecated alias, silent at runtime). See Control points.

Adapters

There is no vendor adapter and no in-process definition poll. See Adapters.

Errors

Same 15-kind FireweaveError taxonomy as the Node SDK. Evaluation never throws. Init throws on configuration failure. See Errors.

Testing

initFireweave({ mode: 'local', … }) or InMemoryWebAdapter. CI uses Bun and happy-dom. See Testing.

Shutdown

A tab has no process shutdown hook. See Initialize, ready, shutdown.

Not in this SDK

  • FireweaveWebProvider / @openfeature/web-sdk
  • releases, exposures, signals, capabilities, guardrails
  • Environment-variable configuration
  • A server entry point / Node-as-target
  • Secret project keys in the browser

Next

Quickstart

Offline evaluate in every language.

Node server SDK

Async server counterpart (@fireweaveai/server-sdk).

Compatibility

Seven-language surface and the 65×7 aggregate.
Last modified on September 11, 2026