SDK reference

Overview

This is the canonical reference for the TypeScript SDK, shipdit. Guides link here for signatures, options, and fallback behavior.

npm install shipdit

Import	Use in	Exports
`shipdit`	Node.js, workers, and other server runtimes	`createClient`, types, version constants
`shipdit/client`	Browsers	`createClient` (with `localStorage` cache and anonymous id), `createLocalStorageCache`, types
`shipdit/client/react`	React client components	`createShipdReact`, types
`shipdit/config`	`shipd.config.ts` only	`defineFlags` — see `shipd.config.ts` reference

Requires Node.js 20 or later. Realtime updates (stream: true) need a WebSocket implementation. Node.js 22+ and browsers provide a global WebSocket; on Node.js 20, pass a compatible constructor through the WebSocket option. Guarantees. Evaluation methods never throw and never make network requests. Before the first snapshot, and for flags missing from it, they return your defaults.

Types

/** Who is asking. Passed per call, or set with identify() in browsers. */
interface EvaluationContext {
  userId?: string;
  attributes?: Record<string, string | number | boolean | null>;
  /** Audience ids the caller already knows it belongs to. */
  segmentIds?: string[];
}

interface IdentifyInput {
  userId: string;
  anonymousId?: string;
  name?: string;
  traits?: Record<string, string | number | boolean | null>;
}

/** Generated by the CLI into src/generated/flags.ts */
interface FlagDefinitions {
  "new-checkout": { type: "boolean"; default: false };
  "search-variant": {
    type: "variant";
    variants: "control" | "semantic" | "hybrid";
    default: "control";
  };
}

type BooleanFlagKey<F> = /* keys of F whose type is "boolean" */;
type VariantFlagKey<F> = /* keys of F whose type is "variant" */;
type NumberFlagKey<F>  = /* keys of F whose type is "number" */;
type JsonFlagKey<F>    = /* keys of F whose type is "json" */;
type VariantValue<F, K> = /* F[K]["variants"] union */;
type JsonValue<F, K>    = /* type of F[K]["default"] */;
type PartialDefaults<F> = { [K in keyof F]?: F[K]["default"] };

interface SnapshotCache {
  load(): Promise<{ snapshot: FlagSnapshot; etag: string | null } | null>;
  save(snapshot: FlagSnapshot, etag: string | null): Promise<void>;
  clear?(): Promise<void>;
}

FlagSnapshot is documented in Snapshots. FlagDefinitions is generated into src/generated/flags.ts; import it from there. The FlagDefinitions type exported by shipdit/config is a different type (the loose authoring map defineFlags accepts), so don’t use it to type a client.

Type	`shipdit`	`shipdit/client`	`shipdit/client/react`
`EvaluationContext`	Yes	Yes	Yes
`BooleanFlagKey`, `VariantFlagKey`, `NumberFlagKey`, `JsonFlagKey`	Yes	Yes	Yes
`VariantValue`, `JsonValue`	Yes	Yes	Yes
`ShipdClient`	Yes	Yes	Yes
`IdentifyInput`, `PartialDefaults`, `SnapshotCache`	Yes	Yes	No
`FlagSnapshot`	Yes	Yes	No
`ClientOptions`	Yes (server options)	Yes (browser options, with `persist`, `storageKey`, `anonymousStorageKey`)	No
`ShipdReact`	No	No	Yes

createClient

Creates a client that downloads one environment’s snapshot and evaluates flags against it in memory.

import { createClient } from "shipdit";         // server
import { createClient } from "shipdit/client";  // browser

createClient<FlagDefinitions>(options: ClientOptions<FlagDefinitions>): ShipdClient<FlagDefinitions>

The client fetches the snapshot immediately, then refreshes it every refreshIntervalMs using If-None-Match. With stream: true, it also refreshes as soon as shipd announces a change. Create one client per process (server) or per page (browser) and reuse it.

Options

string

required

An SDK key for one environment: shipd_sdk_server_… on servers, shipd_sdk_client_… in browsers. See Keys and tokens.

PartialDefaults<FlagDefinitions>

Values returned before the first snapshot arrives and for flags missing from the snapshot. Pass one for every flag. See Defaults.

boolean

default:"false"

Open a WebSocket to https://ws.useshipd.com for near-instant updates. Polling continues as a fallback. Needs a global WebSocket (Node.js 22+, browsers) or the WebSocket option.

ClientOverrides

Connection overrides. Production apps should not set these.

Show properties

string

default:"https://ws.useshipd.com"

WebSocket gateway origin used when stream is true. Accepts https, http, wss, or ws; validated like unsafeEndpoint.

string

default:"https://edge.useshipd.com"

Unsafe. For shipd development and test environments only. Replaces the edge origin that receives your SDK key. Must be an absolute http or https URL without credentials, a query, or a fragment; createClient throws otherwise. A plaintext http URL to a non-local host logs a warning.

EvaluationContext

Base context merged under every evaluation.

number

default:"30000"

Poll interval. Polling continues while the WebSocket is connected. 0 fetches once and never polls.

number

default:"5000"

Maximum time ready() waits for the first snapshot.

number

default:"10000"

Per-request HTTP timeout for snapshot fetches and event flushes. 0 disables the timeout.

FlagSnapshot

A snapshot to evaluate against until the first successful fetch. Use it for server-rendered pages and tests.

SnapshotCache

Durable store for the last good snapshot. Browser clients default to localStorage.

(error: unknown) => void

Receives background fetch, stream, cache, and event-delivery errors. The client keeps working after every error. Messages are listed in Errors.

boolean

default:"true"

Send evaluation, identify, and diagnostic events to POST /sdk/v1/events.

number

default:"50"

Flush when this many events are buffered.

number

default:"5000"

Flush interval. 0 disables timed flushes.

boolean

default:"true"

Browser clients only. After identify(), fetch the user’s last-seen traits from GET /sdk/v1/identity and merge them under the traits you passed.

boolean

Add country, region, city, and timezone under your own attributes. Default true in shipdit/client, off in shipdit.

string

Stable id for a signed-out visitor. Browser clients generate and persist one if omitted.

(anonymousId: string) => void

Called when the client assigns or changes the anonymous id.

WebSocket constructor

WebSocket implementation for runtimes without a global one (for example, ws on Node.js 20).

typeof fetch

fetch implementation. Useful in tests.

Browser-only options (shipdit/client):

boolean

default:"true"

Save the last good snapshot to localStorage and load it on the next page view.

string

localStorage key for the snapshot. Defaults to a key derived from sdkKey and the edge origin.

string

default:"shipdit:anonymousId"

localStorage key for the anonymous id.

Returns a ShipdClient. Errors. Throws synchronously shipdit: sdkKey is required when sdkKey is empty. Removed endpoint or streamEndpoint options and invalid overrides.unsafeEndpoint values also throw synchronously. overrides.streamEndpoint is validated only when stream is enabled; network problems go to onError.

src/lib/shipd.ts

import { createClient } from "shipdit";
import type { FlagDefinitions } from "../generated/flags";

export const shipd = createClient<FlagDefinitions>({
  sdkKey: process.env.SHIPD_SDK_KEY!,
  stream: true,
  defaults: {
    "new-checkout": false,
    "search-variant": "control",
    "max-retries": 3,
    "checkout-payload": { mode: "strict", showPromo: true },
  },
  onError: (error) => console.warn("[shipd]", error),
});

Related: Node.js · Browser · Keys and tokens

Defaults

defaults decides what your users get when shipd can’t answer.

Situation	Value returned
Before the first snapshot (and no `bootstrap` or cached snapshot)	`defaults[key]`
Flag key not in the snapshot (typo, archived, other project)	`defaults[key]`, and an `unregistered_flag` event
Edge unreachable after a successful fetch	Evaluated against the last good snapshot
`defaults[key]` not provided	`false` · `"control"` · `0` · `{}` for boolean · variant · number · JSON

The built-in fallbacks exist only so the return type holds. "control" may not be one of your variants. Always pass a default for every flag.

Client methods

ready

Resolves when the first snapshot is loaded, the first fetch fails, a bootstrap or cached snapshot is available, or readyTimeoutMs elapses.

ready(): Promise<void>

Returns Promise<void>. It never rejects for network errors. Returning on timeout means evaluations use defaults until a snapshot arrives.

await shipd.ready();
server.listen(3000);

Related: Options · useReady

isEnabled

Returns the value of a boolean flag.

isEnabled(key: BooleanFlagKey<FlagDefinitions>, context?: EvaluationContext): boolean

BooleanFlagKey

required

A flag whose type is boolean. Other keys are a type error.

EvaluationContext

Merged over the identified user and the client context for this call only.

Returns boolean. Fallback. See Defaults.

if (shipd.isEnabled("new-checkout", { userId: "usr_8f2k19", attributes: { plan: "pro" } })) {
  return renderNewCheckout();
}

Errors. Never throws. Related: useFlag · Create a boolean flag

getVariant

Returns the value of a variant flag, typed as the union of its variants.

getVariant<K extends VariantFlagKey<FlagDefinitions>>(key: K, context?: EvaluationContext): VariantValue<FlagDefinitions, K>

VariantFlagKey

required

A flag whose type is variant.

EvaluationContext

Per-call context.

Returns one of the flag’s variants, for example "control" | "semantic" | "hybrid". Fallback. See Defaults.

const engine = shipd.getVariant("search-variant", { userId: "usr_8f2k19" });

Errors. Never throws. Related: useVariant · Run an A/B test

getNumber

Returns the value of a number flag.

getNumber(key: NumberFlagKey<FlagDefinitions>, context?: EvaluationContext): number

Returns a finite number. A non-finite served value falls back to defaults[key].

const retries = shipd.getNumber("max-retries");

Errors. Never throws. Related: useNumber · Number and JSON flags

getJson

Returns the value of a JSON flag, typed as its declared default.

getJson<K extends JsonFlagKey<FlagDefinitions>>(key: K, context?: EvaluationContext): JsonValue<FlagDefinitions, K>

Returns the served JSON value. The type comes from the default in shipd.config.ts; the SDK does not validate the served value’s shape.

const ui = shipd.getJson("checkout-payload");
// { mode: "strict"; showPromo: true }

Errors. Never throws. Related: useJson

identify

Sends an identify event. In browsers (shipdit/client), it also sets the user for every later evaluation on the client. On servers (shipdit), it only sends the event and never changes evaluation context.

identify(input: IdentifyInput): void

string

required

Your stable user id. Used for targeting and percentage bucketing.

Record<string, string | number | boolean | null>

Attributes available to targeting rules, such as plan or email.

string

Display name shown in the dashboard. Also available to rules as the name attribute.

string

Links this user to a signed-out session.

Errors. Throws shipdit: identify requires userId when userId is empty.

// Browser
shipd.identify({ userId: "usr_8f2k19", name: "Jordan Chen", traits: { plan: "pro" } });
shipd.isEnabled("new-checkout"); // evaluated for usr_8f2k19

A server client handles many users, so pass context on each call. Server identify() records the user’s traits for audience insights without affecting other requests. Related: Identify users

reset

Clears the identified user and starts a new anonymous id in browser clients. Call it on logout. Server clients (shipdit) treat reset() as a no-op: it does not change the anonymous id or notify subscribers.

reset(): void

getAnonymousId

Returns the anonymous id used to connect signed-out and signed-in sessions, or null.

getAnonymousId(): string | null

Calls listener when a new snapshot applies or the identified user changes.

subscribe(listener: () => void): () => void

Returns an unsubscribe function.

const unsubscribe = shipd.subscribe(() => render());

getVersion

Returns the loaded snapshot’s version, or null before the first snapshot.

getVersion(): number | null

getRevision

Returns a counter that increases whenever a snapshot applies or the identity changes. Use it with useSyncExternalStore.

getRevision(): number

close

Stops polling and the WebSocket, and flushes pending events. Call it on shutdown. Evaluation keeps serving the last snapshot afterward.

close(options?: { timeoutMs?: number }): Promise<void>

number

default:"5000"

How long to wait for pending events. When it passes, pending sends are aborted and the promise resolves.

The promise resolves once pending events are delivered, delivery fails, or timeoutMs passes. It never rejects. Events recorded while a send is in flight are delivered too, in batches of at most 100.

process.on("SIGTERM", async () => {
  await shipd.close();
});

Evaluation context merge

The context used for a check is built from three layers. Later layers win.

createClient({ context })
identify({ userId, traits }) (browser clients only): traits become attributes
The context argument on the call

userId and segmentIds are replaced. attributes merge key by key. In browsers, automatic timezone and location traits sit underneath all three.

React

createShipdReact

Binds typed hooks and a provider to your FlagDefinitions. Call it once, in a client-only module.

import { createShipdReact } from "shipdit/client/react";

createShipdReact<FlagDefinitions>(): {
  ShipdProvider, useShipdClient, useReady, useFlag, useVariant, useNumber, useJson
}

src/lib/shipd-react.ts

"use client";

import { createShipdReact } from "shipdit/client/react";
import type { FlagDefinitions } from "../generated/flags";

export const { ShipdProvider, useFlag, useVariant, useNumber, useJson, useReady, useShipdClient } =
  createShipdReact<FlagDefinitions>();

Use hooks from the same createShipdReact call as the provider. Requires React 18 or later. Related: React · Next.js

ShipdProvider

Makes a client available to hooks below it.

<ShipdProvider client={client}>{children}</ShipdProvider>

ShipdClient

required

A client from shipdit/client.

useFlag

isEnabled as a hook. Re-renders when a snapshot applies or the identity changes.

useFlag(key: BooleanFlagKey, context?: EvaluationContext): boolean

useVariant

useVariant<K extends VariantFlagKey>(key: K, context?: EvaluationContext): VariantValue<FlagDefinitions, K>

useNumber

useNumber(key: NumberFlagKey, context?: EvaluationContext): number

useJson

useJson<K extends JsonFlagKey>(key: K, context?: EvaluationContext): JsonValue<FlagDefinitions, K>

useReady

Returns true once client.ready() has resolved.

useReady(): boolean

useShipdClient

Returns the provided client.

useShipdClient(): ShipdClient<FlagDefinitions>

Errors. Throws when used outside ShipdProvider.

Version constants

import { VERSIONS } from "shipdit";
// { snapshotSchema, streamProtocol, sdkPackage, controlPlaneApi }

Constant	Current	Meaning
`SNAPSHOT_SCHEMA_VERSION`	`1`	Snapshot format this SDK reads. Newer formats are rejected and the last good snapshot is kept.
`SDK_STREAM_PROTOCOL_VERSION`	`1`	WebSocket protocol version.
`SDK_PACKAGE_VERSION`	package version	The installed `shipdit` version.
`CONTROL_PLANE_API_VERSION`	`1`	Control-plane API major version (`/api/v1`).

Local evaluation: the refresh path and failure behavior
Edge API: the HTTP and WebSocket routes the SDK calls
Errors: onError messages

SDK setup

SDK reference

Config and CLI reference

SDK reference

Overview

Types

createClient

Options

Defaults

Client methods

ready

isEnabled

getVariant

getNumber

getJson

identify

reset

getAnonymousId

getVersion

getRevision

close

Evaluation context merge

React

createShipdReact

ShipdProvider

useFlag

useVariant

useNumber

useJson

useReady

useShipdClient

Version constants

​Overview

​Types

​createClient

​Options

​Defaults

​Client methods

​ready

​isEnabled

​getVariant

​getNumber

​getJson

​identify

​reset

​getAnonymousId

​subscribe

​getVersion

​getRevision

​close

​Evaluation context merge

​React

​createShipdReact

​ShipdProvider

​useFlag

​useVariant

​useNumber

​useJson

​useReady

​useShipdClient

​Version constants

​Related

Overview

Types

createClient

Options

Defaults

Client methods

ready

isEnabled

getVariant

getNumber

getJson

identify

reset

getAnonymousId

subscribe

getVersion

getRevision

close

Evaluation context merge

React

createShipdReact

ShipdProvider

useFlag

useVariant

useNumber

useJson

useReady

useShipdClient

Version constants

Related