JavaScript Client SDK

The FlagTGL JavaScript Client SDK is designed for browser-based applications. It fetches flag evaluations from the relay proxy and keeps them updated in real time.

Safe behavior when FlagTGL is unavailable

The second argument to a variation call is the application-defined fallback. If FlagTGL is unreachable and the SDK has no bootstrap or last-known-good value, that fallback is served. A false fallback means Disabled for all contexts:

const enabled = client.boolVariation('new-rbac', false)

Installation

npm install @flagtgl/js-client-sdk

Quick Start

import { FlagTGLClient } from '@flagtgl/js-client-sdk';

const client = new FlagTGLClient('your-client-sdk-key', {
  key: 'user-123',
  custom: { plan: 'pro' }
});

await client.waitForInitialization();
const enabled = client.variation('my-flag', false);

The client SDK is compatible with the LaunchDarkly JavaScript SDK interface. See the Migration Guide for details.

Offline / appliance bootstrap

For standalone appliances (e.g. AMIs) that may run fully offline, the SDK can resolve flags local-first:

1. Local bootstrap file — a same-origin JSON file baked into or mounted onto the appliance and served by the local web server (e.g. nginx).
2. Remote flagtgl server — refreshes and overrides local values whenever it is reachable.
3. Code defaults — the default passed to each variation call, used per flag read when neither source knows the flag.

The client fires ready as soon as the bootstrap file (or the localStorage last-known-good cache) provides flags — it never blocks readiness on the network. If the server is unreachable, local values keep being served and the SDK retries quietly in the background with exponential backoff (capped at 60s); there is no console spam on offline boxes.

AMI pattern

Bake or mount the bootstrap file on the appliance and let nginx serve it alongside your app:

location = /elastio-flags.json {
    root /opt/elastio/config;   # baked into the AMI or mounted at boot
    default_type application/json;
}

/opt/elastio/config/elastio-flags.json:

{
  "flags": {
    "new-checkout-flow": true,
    "max-parallel-scans": 4,
    "banner-text": "Running in appliance mode"
  }
}

A bare map (without the "flags" wrapper) is also accepted: {"new-checkout-flow": true, ...}.

Point the SDK at the file:

import { FlagsClient } from '@flagtgl/js-sdk';

const client = new FlagsClient({
  sdkKey: 'sdk-cli-your-key',
  baseURL: 'https://flags.example.com',
  bootstrapURL: '/elastio-flags.json',   // same-origin local file
  user: { key: 'appliance-1' },
});

await client.initialize();               // ready immediately from the local file
const enabled = client.boolVariation('new-checkout-flow', false);

Configuration options

Option	Type	Default	Description
bootstrapURL	string	—	Same-origin URL of a bootstrap JSON file. Fetched with a short timeout during initialize(); failures are ignored silently.
bootstrap	object	—	Inline bootstrap values (takes precedence over bootstrapURL). Accepts {"flags": {...}} or a bare {"flag-key": value} map.
cacheKey	string | false	derived from sdkKey	localStorage key for the last-known-good flag cache, refreshed after every successful remote evaluation. Pass false to disable caching.
remoteEnabled	boolean	true	Set to false for pure offline mode: the server is never contacted and only bootstrap/cache values (plus code defaults) are used.

On conflicts, bootstrap values win over cached values at startup; once a remote evaluation succeeds, remote values replace the store (a change event fires for each changed key) and streaming updates attach.

The React SDK (@flagtgl/react-sdk) forwards all of these options through FlagTGLProvider.

note

Full SDK reference documentation is coming soon.