@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.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
- npm 2.1.0
- From checkout
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 includeSTALE: 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.
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.
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).
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.
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-kindFireweaveError 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
Not in this SDK
- Environment-variable configuration
- PostHog / vendor adapter
- In-process local evaluation (
localEvaluationcannot become true) - Server entry point / Node-as-target
- A client method named
registerTarget(useidentify) - 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.