Use SwitchPilot with Node.js

Control product features from Node.js backends, APIs, and server-side TypeScript.

Server-side essentials
Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

Node.js SDK

@switchpilot/node

v0.2.0

Node.js 18+

Requirements

The official Node SDK requires Node.js 18 or newer and is designed for server-side usage only.

It works with Next.js, Node.js backends, API routes, Server Actions, Express, NestJS, and backend services.

1. Install the SDK

terminal
pnpm add @switchpilot/node

2. Configure the API key

.env
SWITCHPILOT_API_KEY="sp_live_xxxxxxxxx"

The key is shown once. If it is lost, regenerate it in Project Settings and replace SWITCHPILOT_API_KEY before restarting or redeploying the service. The previous key stops working immediately.

3. Initialize the client and check a flag

switchpilot.ts
import { createSwitchPilot } from "@switchpilot/node";

const flags = createSwitchPilot({
  apiKey: process.env.SWITCHPILOT_API_KEY!,
});

const enabled = await flags.isEnabled("new-dashboard");

Use the client in your backend

checkout.ts
const enabled = await flags.isEnabled("new-checkout");

if (enabled) {
  await processNewCheckout();
} else {
  await processCurrentCheckout();
}

Available methods

flags.ts
const enabled = await flags.isEnabled("new-checkout");
const allFlags = await flags.getAll();
const freshFlags = await flags.refresh();
const status = flags.getStatus();

getAll() uses a valid cache. refresh() always attempts a network request.

Local evaluation and synchronization

switchpilot.ts
const flags = createSwitchPilot({
  apiKey: process.env.SWITCHPILOT_API_KEY!,
  cacheTtlMs: 60_000,
  staleIfErrorMs: 300_000,
  fallback: false,
});

The default cache TTL is 60 seconds. While it is fresh,isEnabled()and getAll() read only local memory. A dashboard change can therefore take about one minute to appear unless you call refresh() manually.

The SDK uses ETags automatically. An unchanged configuration returns 304 and renews freshness without downloading the flags again. Concurrent callers share one network refresh.

Last Known Good and rate limits

If synchronization fails, the last valid configuration remains usable for five minutes after its normal TTL by default. The fallback is used only when no usable configuration exists. On 429, the SDK respects Retry-After and does not contact the API again before that deadline. Use getStatus() to inspect stale use and rate limiting without triggering a request.

Safe fallback behavior

Missing flags, invalid responses, timeouts and normal network failures resolve to false unless you set a different client-level or per-call fallback. Flag evaluation does not throw for those failures.

per-call fallback
await flags.isEnabled("new-checkout", true);