JavaScript SDK

The browser SDK for ToggleTown. Use this in client-side JavaScript applications (vanilla JS, Vue, Svelte, etc). For React, see the React SDK. For server-side Node.js, see the Node.js SDK.

Package: @toggletown/sdk-js

Installation

npm install @toggletown/sdk-js

Quick Start

import { ToggleTownClient } from '@toggletown/sdk-js';

const client = new ToggleTownClient('tt_live_your_api_key', {
  apiUrl: 'https://api.toggletown.com',
});

await client.initialize();

const enabled = client.getBooleanFlag('new-feature', false, {
  userId: 'user-123',
  plan: 'pro',
});

if (enabled) {
  showNewFeature();
}

// Clean up when done
client.close();

Configuration

const client = new ToggleTownClient('tt_live_your_api_key', {
  apiUrl: 'https://api.toggletown.com',   // API endpoint (default: https://api.toggletown.com)
  pollingInterval: 30000,                  // Milliseconds between flag refreshes (default: 30000)
  onError: (error) => {                    // Called on fetch errors after initialization
    console.error('Flag error:', error);
  },
});

Option	Type	Default	Description
apiUrl	string	https://api.toggletown.com	API endpoint URL
pollingInterval	number	30000	Polling interval in ms
onError	(error: Error) => void	—	Error callback for background fetch failures

Flag Types

Boolean

const enabled = client.getBooleanFlag('feature-enabled', false, context);

String

const variant = client.getStringFlag('experiment-variant', 'control', context);

Number

const maxItems = client.getNumberFlag('max-items', 10, context);

JSON

const config = client.getJSONFlag('feature-config', { enabled: false }, context);

User Context

Pass user attributes for targeting rules and percentage rollouts:

const context = {
  userId: 'user-123',       // Required for percentage rollouts
  email: '[email protected]',
  plan: 'enterprise',
  country: 'US',
  betaUser: true,
};

const enabled = client.getBooleanFlag('premium-feature', false, context);

Initialization

The SDK must be initialized before evaluating flags. initialize() fetches flags from the API and starts background polling.

const client = new ToggleTownClient('tt_live_xxx');

try {
  await client.initialize();
  // Flags are now available
} catch (error) {
  // Initial fetch failed — use defaults
  console.error('Failed to initialize:', error);
}

You can also check initialization status:

if (client.isInitialized()) {
  // Safe to evaluate flags
}

// Or wait for initialization
await client.waitForInitialization();

Error Handling

• Initialization errors are thrown — you must catch them
• Polling errors are logged to console and passed to the onError callback
• When polling fails, the SDK continues using cached flag values

const client = new ToggleTownClient('tt_live_xxx', {
  onError: (error) => {
    // Send to error tracking
    Sentry.captureException(error);
  },
});

Debugging

Get all flag configurations for debugging:

const flags = client.getAllFlags();
console.log(flags);
// { "my-flag": { enabled: true, rolloutPercentage: 100, ... }, ... }

Cleanup

Always close the client when you're done to stop background polling:

client.close();

TypeScript

The SDK is written in TypeScript and exports all types:

import {
  ToggleTownClient,
  ToggleTownConfig,
} from '@toggletown/sdk-js';
import type { EvaluationContext, FlagConfig } from '@toggletown/types';