featuretoggle-sdk-typescript

TypeScript SDK for reading features from the FeatureToggle public API — browser client and Node server entry. Plain JavaScript works.

Install

npm install featuretoggle-sdk-typescript
# or
pnpm add featuretoggle-sdk-typescript
# or
yarn add featuretoggle-sdk-typescript
# or
bun add featuretoggle-sdk-typescript

Both entries ship ESM, CJS, and types:

| Entry | Use for | |-------|---------| | featuretoggle-sdk-typescript | Browser — SSE, subscribe(), close() | | featuretoggle-sdk-typescript/server | Node — init() + refresh() only |

// ESM
import { FeatureToggle } from "featuretoggle-sdk-typescript";
import { FeatureToggleServer } from "featuretoggle-sdk-typescript/server";

// CJS
const { FeatureToggle } = require("featuretoggle-sdk-typescript");
const { FeatureToggleServer } = require("featuretoggle-sdk-typescript/server");

React UI: featuretoggle-sdk-react.

Quick start

import { FeatureToggle } from "featuretoggle-sdk-typescript";

const ft = new FeatureToggle({
  apiKey: import.meta.env.VITE_FT_API_KEY!,
});

await ft.init();

if (ft.isEnabled("new-checkout")) {
  // ...
}

const theme = ft.getValue<string>("theme-variant");
ft.subscribe(() => {
  /* cache updated */
});
ft.close();

Server entry:

import { FeatureToggleServer } from "featuretoggle-sdk-typescript/server";

const ft = new FeatureToggleServer({
  apiKey: process.env.FT_API_KEY!,
});

await ft.init();
await ft.refresh();

if (ft.isEnabled("new-checkout")) {
  // ...
}

Cookbook

Full recipes in INTEGRATION.md (Cookbook):

| Pattern | See | |---------|-----| | SPA singleton | INTEGRATION.md | | Subscribe without a framework | INTEGRATION.md | | Seeded cache (SSR handoff) | INTEGRATION.md | | Manual lifecycle | INTEGRATION.md | | Module singleton | INTEGRATION.md | | Per-request server instance | INTEGRATION.md | | API route / middleware gate | INTEGRATION.md | | TTL refresh | INTEGRATION.md | | SSR split | INTEGRATION.md |

React patterns: React cookbook.

API

FeatureToggle

Options: apiKey (or FT_API_KEY), stream (default "auto"), pollInterval (default 30 when stream: "off"; 0 disables; or FT_POLL_INTERVAL), initialFeatures / initialEtag, fetch.

| Method | Description | |--------|-------------| | init() | Fetch features and open SSE stream | | refresh() | Refetch features now | | isEnabled(key) | true when the feature is enabled in cache | | getValue<T>(key) | Resolved value or undefined | | getFeatures(options?) | Filtered copy of cached features | | subscribe(listener) | Callback when cache updates; returns unsubscribe | | close() | Close stream and stop transport |

stream / pollInterval semantics: Caching and syncs. Shared env vars: SDKs.

FeatureToggleServer

Same read methods plus init() and refresh(). No close() or background transport. Options: apiKey, optional fetch.

FeatureResponse

key, type, value, enabled, deprecated, optional inFavorOf. HTTP contract: Feature API.

Enabled deprecated features are included in the bulk fetch. The SDK logs a one-time console.warn per key on isEnabled() / getValue(). On 401, cache clears and transport stops. On 403, one-time console.warn per instance with the API message.