Split Thin Client SDK for JavaScript

JavaScript implementation of the Split thin client SDK (@splitsoftware/splitio-thin-client).

This SDK retrieves treatments from the remote evaluator service (instead of computing locally), supports event tracking, and includes polling/streaming synchronization modes.

Install

npm install @splitsoftware/splitio-thin-client

Quick Start

import { SplitFactory } from '@splitsoftware/splitio-thin-client';

const factory = SplitFactory({
  sdkKey: 'YOUR_SDK_KEY',
  target: {
    key: { matchingKey: 'CUSTOMER_ID' },
    trafficType: 'user',
    attributes: { plan: 'premium' },
  },
});

const client = factory.getClient();

// Attach listeners right after getClient().
client.on(client.Event.SDK_READY, () => {
  const result = client.getTreatment('my-feature');
  console.log(result.treatment);
});

// Or check readiness synchronously:
if (client.isReady()) {
  console.log(client.getTreatment('my-feature').treatment);
}

Important Usage Notes

• Attach .on(client.Event.SDK_READY, ...) immediately after getClient().
• Wait for SDK_READY (or check client.isReady()) before evaluating flags for remote values.
• Calling getTreatment() before readiness may return control (or configured fallback).
• Use factory.destroy() during shutdown to stop sync and flush queued data.

Configuration

Config options live at the top level of the settings object, alongside sdkKey and target:

import { SplitFactory, createLocalStorage } from '@splitsoftware/splitio-thin-client';

const factory = SplitFactory({
  sdkKey: 'YOUR_SDK_KEY',
  target: {
    key: { matchingKey: 'CUSTOMER_ID' },
    trafficType: 'user',
    attributes: { plan: 'premium' },
  },

  logLevel: 'info',
  configsEnabled: false,
  // Optional browser persistence. Pass the prefix directly; omit `storage`
  // entirely for in-memory only.
  storage: createLocalStorage('my_app'),
  sync: {
    mode: 'streaming',  // 'streaming' | 'polling' | 'single_sync'
    readyTimeout: 10,   // seconds (-1 disables the timeout)
    pollingRate: 60000, // milliseconds
    pushRate: 60000,    // milliseconds
    // Hosts only — the SDK appends paths (e.g. /api/evaluations) internally.
    serviceEndpoints: {
      api: 'https://evaluator.split.io',
      auth: 'https://auth.split.io',
      events: 'https://events.split.io',
      streaming: 'https://streaming.split.io',
    },
  },
  filters: {
    flagSets: ['set_1', 'set_2'], // optional: filter by flag sets
  },
  // Returned in place of 'control' when the SDK can't evaluate a flag
  // (e.g. not ready yet, flag not found, or a parse error).
  fallbackTreatments: {
    global: 'off', // string, or { treatment: 'off', config: '{"reason":"fallback"}' }
    byFlag: {
      'my-feature': { treatment: 'on', config: '{"color":"blue"}' },
    },
  },
});

A flag listed in byFlag takes precedence over global. Each value can be a plain treatment string or an object with an optional dynamic config string.

TypeScript Types

Public types are exposed through the ambient SplitIO namespace, merged with the one declared by @splitsoftware/splitio-commons. Import the runtime entry points and reference every type via SplitIO.* — no extra type imports or triple-slash directives required.

import { SplitFactory, createLocalStorage } from '@splitsoftware/splitio-thin-client';

const settings: SplitIO.SplitFactorySettings = {
  sdkKey: 'YOUR_SDK_KEY',
  target: {
    key: { matchingKey: 'CUSTOMER_ID' },
    trafficType: 'user',
  },
  storage: createLocalStorage('my_app'),
};

const factory: SplitIO.SDK = SplitFactory(settings);
const client: SplitIO.SplitClient = factory.getClient();
const manager: SplitIO.SplitManager = factory.manager();

client.on(client.Event.SDK_READY, (metadata: SplitIO.SdkReadyMetadata) => {
  const result: SplitIO.EvaluationResult = client.getTreatment('my-feature');
  console.log(result.treatment);
});

Commonly used names: SplitClient, SDK, SplitManager, SplitFactorySettings, SplitClientConfig, SyncConfig, StorageConfig, ServiceEndpoints, Target, TargetInput, Key, KeyInput, EvaluationResult, IClientEvents, SdkReadyListener, SdkReadyFromCacheListener, SdkUpdateListener, SdkReadyTimedOutListener, and PersistentStorage. Commons types such as SplitIO.EvaluationOptions, SplitIO.Properties, SplitIO.Attributes, SplitIO.EventConsts, and SplitIO.FallbackTreatmentConfiguration are reachable through the same namespace.

Supported Browsers

The SDK is distributed as ES2015 and targets modern browsers. Every Web API it relies on is Baseline Widely Available. The minimum versions are:

| Browser | Minimum version | | --- | --- | | Chrome / Chrome for Android | 57 | | Edge (Chromium) | 79 | | Firefox | 54 | | Safari (macOS) | 10.1 | | iOS Safari | 10.3 |

Internet Explorer and legacy (EdgeHTML) Edge are not supported.

Notes:

• Fetch: provided via the bundled cross-fetch dependency, so no Fetch polyfill is required.
• Content digest: requests include a content-digest header computed with SHA-512. The native Web Crypto API (crypto.subtle) is used when available (secure contexts: HTTPS, localhost, file://); on insecure origins the SDK transparently falls back to a bundled pure-JS implementation, so evaluations work everywhere. HTTPS is still recommended in production.
• Streaming: uses the native EventSource (SSE) API. Where it is unavailable, the SDK automatically degrades to polling.
• Persistence: createLocalStorage(prefix?) is optional and feature-detected; it returns undefined when localStorage is unavailable (e.g. SSR), in which case the SDK runs in-memory only.

Development

# Install deps
npm install

# Build
npm run build

# Lint + typecheck
npm run lint

# Unit/integration tests
npm test

Browser Demo

See examples/README.md for the interactive browser demo:

• bundle SDK for browser
• run local demo server
• test sync modes, events, and target switching

Repository Structure

• src/client - public factory/client/manager wiring
• src/evaluation - storage/repository/fetch coordination
• src/auth - credential fetching, caching, secure HTTP
• src/streaming - SSE manager and notification handling
• src/eventsTracking - event queue, submitter, scheduler
• src/observability - SDK/internal event mapping and logging
• __tests__ - unit, integration, and E2E coverage