GrowthBook JS SDK

The GrowthBook JavaScript SDK is the client library for GrowthBook, an open-source feature flagging and experimentation platform. It evaluates feature flags and runs A/B tests entirely on the client, with no external runtime dependencies beyond the DOM-mutation helper used for visual experiments, and it works identically in modern browsers and Node.js.

Rather than making a network round-trip on every flag check, the SDK downloads a payload of feature and experiment definitions once (optionally streamed live over Server-Sent Events) and evaluates targeting rules locally in-memory. This avoids the flicker that plagues many feature-flagging integrations and keeps flag checks synchronous and fast. It supports encrypted payloads, sticky bucketing for consistent experiment assignment across sessions, contextual bandits, remote configuration, and visual (no-code) experiments driven by the GrowthBook Visual Editor.

What You Get

• A GrowthBook class for per-request/per-user instances (ideal for SPAs and one-instance-per-request server setups) and a GrowthBookClient for a shared singleton that accepts a user context per call (ideal for high-throughput servers)
• Built-in fetching, caching, retry logic, and background refresh for feature payloads, with optional realtime updates over Server-Sent Events
• Local, synchronous rule evaluation for boolean, string, number, and JSON feature values via isOn and getFeatureValue, so there’s no per-check network latency or UI flicker
• Support for encrypted feature payloads (via a decryptionKey), sticky bucketing so users stay in the same experiment variation across sessions, and contextual bandit-driven experiments
• A plugin system (auto-attributes, third-party-tracking, growthbook-tracking, devtools) for wiring up targeting attributes and forwarding experiment views to analytics tools automatically
• No-code Visual Experiments: DOM mutations defined in the GrowthBook Visual Editor are applied client-side via the dom-mutator dependency, with URL redirect and page-targeting support

Common Use Cases

• Rolling out a new feature gradually to a percentage of users without a redeploy, using a boolean flag evaluated with isOn
• Running an A/B test on button copy, pricing, or layout and reporting variation exposure to an existing analytics stack (GA, Segment, Mixpanel) via trackingCallback
• Building a multi-tenant Node.js API where a shared GrowthBookClient singleton evaluates flags per-request using a lightweight userContext instead of instantiating a client per request
• Running visual, no-code experiments (copy/style changes) defined non-technically in the GrowthBook dashboard and applied automatically in the browser
• Keeping feature rollout consistent for a given user across multiple sessions or devices using sticky bucketing

Under The Hood

Architecture The SDK is organized as a small set of single-responsibility modules rather than one monolithic client: core.ts holds pure, side-effect-free evaluation logic (feature resolution, experiment bucketing, sticky-bucket lookups, tracking-context assembly) that is shared by both public entry points; GrowthBook.ts wraps that core in a stateful, per-instance class aimed at single-user contexts (SPAs, one-instance-per-request servers), while GrowthBookClient.ts wraps the same core in a shared, multi-user singleton that takes a userContext argument on each call; feature-repository.ts owns all networking concerns — fetch, response caching with staleness, exponential-backoff polling, and Server-Sent-Events subscriptions — kept entirely separate from evaluation; and mongrule.ts implements a MongoDB-style condition-matching DSL used purely for targeting-rule evaluation. This separation means the core evaluation logic has no knowledge of HTTP, and the two public client classes differ only in how they thread user state through the same evaluation path.

Tech Stack Written in strict-mode TypeScript with esModuleInterop, the SDK ships as dual ESM/CJS builds compiled via Babel (build:esm/build:cjs) plus a browser-ready global bundle produced with Rollup, with type declarations emitted separately via tsc --emitDeclarationOnly and additionally validated through TypeScript’s native-preview compiler (tsgo). Its only runtime dependency is dom-mutator, used to apply DOM changes for no-code Visual Experiments; everything else — fetch, EventSource, SubtleCrypto, localStorage — is provided by the host environment or injected through an explicit setPolyfills API for older Node.js versions.

Code Quality The package has 18 dedicated test files under test/ covering experiments, sticky buckets, contextual bandits, feature repository behavior, URL redirects, condition evaluation, and each bundled plugin, run with Jest/ts-jest against a jsdom environment. The codebase enforces strict: true TypeScript compilation, uses a shared ESLint flat config (with project-specific custom rules) across the monorepo, and is checked in a dedicated CI workflow; error handling around network calls (fetch failures, SSE errors, decryption failures) is explicit rather than silently swallowed, with configurable retry/backoff behavior.

What Makes It Unique Unlike many feature-flag SDKs that require a network call (or a server-side proxy) on every flag check, this SDK evaluates targeting rules and experiment assignment entirely client-side against a payload fetched once, eliminating both per-check latency and UI flicker while still supporting realtime updates via SSE streaming. It further differentiates itself by supporting no-code Visual Experiments (applying DOM mutations authored in a GUI editor without touching application code), encrypted feature payloads for sensitive targeting logic, sticky bucketing for assignment consistency, and native support for contextual-bandit-style experiments — all as first-class, well-tested capabilities rather than SDK add-ons.