Skip to main content
@fireweaveai/web-sdk is the FireWeave browser binding. It evaluates control points synchronously from a prefetched cache, registers targets via identify(), and records exposures and signals. OpenFeature and the wire protocol still use flagKey. This is a different surface from @fireweaveai/sdk. It is not a Node, Bun, or Deno server target.
@fireweaveai/web-sdk@2.1.0 is on npm (verified 2026-08-17; tarball gitHead matches master dfeb478). There is no web-specific README install command in the SDK tree. Pin @2.1.0, or build from checkout for an unreleased tree.
Today’s constructor key is still a project-api-key_… / attest family. Spec/ADR-0009: a scoped fw_public_… key with flags:evaluate + events:write is required before production browser use. Whether fw-server already issues fw_public_… is NEEDS VERIFICATION (platform work). Do not bake attest:write keys into a frontend bundle as if they were public.

Supported runtime

It ships no server entry point, reads no environment, and imports no runtime built-ins. Node and Deno are not target runtimes.

Install

Verified 2026-08-17 on npm (@fireweaveai/web-sdk@2.1.0).

Initialize

Reads are synchronous. initialize() and setContext() prefetch asynchronously; evaluate / OpenFeature resolvers read the cache.
FireweaveWebProvider metadata default name: fireweave-web. runsOn = 'client'. resolve*Evaluation returns ResolutionDetails, never a Promise.

Lifecycle and STALE

States include STALE: prefetch raced DEFAULT_FLAGS_READY_TIMEOUT_MS (5000) and lost. Reads are defaults with reason STALE. Collapsing STALE into READY is rejected in the runtime — a timed-out boot must stay distinguishable from a successful one where every control point is off. The provider emits OpenFeature Stale and, on context change, ConfigurationChanged with only keys whose decisions moved.

Configuration and authentication

FireweaveRemoteWebAdapterOptions: apiUrl and apiKey are required constructor fields. The package reads no environment.
Rejects phc_ / phs_ / phx_ key shapes (assertNotSecretKey) with Configuration. Default allowlist matches Node: 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/capture, /v1/targets/register. localEvaluation is structurally false. See Configuration and auth.

Targets: identify (not registerTarget on the client)

Web exposes FireweaveWebClient.identify. It calls runtime.registerTarget, then setContext({ targetingKey }) so the next prefetch buckets on that id.
This is not OpenFeature identify and not analytics identify. Options match RegisterTargetOptions: kind?: 'user' | 'device', properties?, environment?. See Targeting and targets.

Control points (synchronous)

ExpectedFlagType: 'boolean' | 'string' | 'number' | 'object' — same number model as Node (IEEE-754 double).
Helpers: getBooleanValue, getStringValue, getNumberValue, getObjectValue. All sync. Evaluation never throws. See Control points.

Releases, exposures, signals, capabilities

Same extension set as the server client: releases, exposures, signals, capabilities, plus the guardrails stub. Exposures flush on visibilitychange → hidden and pagehide via keepalive / sendBeacon (autoFlushOnUnload defaults on; pass { autoFlushOnUnload: false } in tests). Dedup is per (flagKey, targetingKey, variant) in web tests.
sendExposure on evaluate defaults to false (same ruling as server SDKs). See Releases, Exposures, Signals, Capabilities.

Adapters

There is no PostHog / vendor adapter and no in-process local evaluation.
See Adapters.

OpenFeature

FireweaveWebProvider + @openfeature/web-sdk ^1.9.0. Resolvers are sync. Options: { name? } (default fireweave-web). Tracking is not implemented. See OpenFeature.

Errors

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

Testing

InMemoryWebAdapter + optional { autoFlushOnUnload: false }. CI uses Bun and happy-dom. happy-dom cannot prove bfcache restore, beacon size limits, or that an unload request leaves the socket. See Testing.

Shutdown

A tab has no process shutdown hook; unload flush is the substitute. See Initialize, ready, shutdown.

Not in this SDK

  • Environment-variable configuration
  • PostHog / vendor adapter
  • In-process local evaluation (localEvaluation cannot become true)
  • Server entry point / Node-as-target
  • A client method named registerTarget (use identify)
  • Working guardrails
  • OpenFeature Tracking

Next

Quickstart

Offline evaluate in every language.

Node server SDK

Async server counterpart (@fireweaveai/sdk).

Compatibility

Type split, adapters, and conformance.
Last modified on August 18, 2026