Evaluate flags in your app

Overview

Jordan wires Fieldkit’s API to shipd. Flag checks are in-memory. The network is only for downloading the snapshot (evaluation payload) and optional realtime invalidation. This guide uses the flags from Define flags in code.

Install

pnpm add shipdit

Create a server SDK key in the dashboard. It looks like shipd_sdk_server_… and is shown once.

Server (Node, workers)

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!,
  endpoint: process.env.SHIPD_EDGE_URL ?? "https://edge.useshipd.com",
  streamEndpoint: process.env.SHIPD_WS_URL, // e.g. https://ws.useshipd.com
  defaults: {
    "new-checkout": false,
    "search-variant": "control",
    "max-retries": 3,
    "checkout-payload": { mode: "strict", showPromo: true },
  },
});

src/checkout.ts

import { shipd } from "./lib/shipd";

await shipd.ready();

export function pickCheckout(userId: string) {
  if (shipd.isEnabled("new-checkout", { userId })) {
    return "new";
  }
  return "legacy";
}

export function searchEngine(userId: string) {
  return shipd.getVariant("search-variant", { userId });
  // ^? "control" | "semantic" | "hybrid"
}

export function retryBudget() {
  return shipd.getNumber("max-retries");
}

export function checkoutUi() {
  return shipd.getJson("checkout-payload");
}

ready() never rejects for network errors. On timeout it resolves anyway and you serve defaults until a snapshot arrives.

Browser

src/lib/shipd-browser.ts

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

export const shipd = createClient<FlagDefinitions>({
  sdkKey: "shipd_sdk_client_…",
  endpoint: "https://edge.useshipd.com",
  streamEndpoint: "https://ws.useshipd.com",
  defaults: { "new-checkout": false, "search-variant": "control" },
});

await shipd.ready();

Browser clients persist the last good snapshot (and a stable anonymousId) in localStorage unless you pass persist: false.

Client and server keys currently receive the same targeting rules. Prefer server keys for backends. Client keys are safe to embed; reduced client snapshots come later.

Context on a check

shipd.isEnabled("new-checkout", {
  userId: "usr_8f2k19",
  attributes: { plan: "pro", country: "US" },
});

Without userId, percentage rollouts cannot bucket — the user falls through. Set a default identity with identify.

Polling and realtime

GET /sdk/v1/snapshot with If-None-Match
200 — replace the in-memory snapshot
304 — keep it
Optional WebSocket streamEndpoint → /sdk/v1/stream → on snapshot.updated, refetch
Poll every refreshIntervalMs (default 30_000) even if the socket is up

Omit streamEndpoint for polling only. refreshIntervalMs: 0 fetches once. If the edge is unreachable, the last good snapshot (or defaults) stays. Evaluation never throws.

shipd.close(); // stop polling + stream

Failure modes

Situation	What you get
Edge down / timeout	`defaults` or last good snapshot
Unknown flag key	`defaults` + `unregistered_flag` event
HTTP 401 (revoked key)	last good snapshot; `onError`
Snapshot `schemaVersion` you don’t support	last good snapshot; `onError`

Getting started

Guides

How-to

Concepts

Reference

Evaluate flags in your app

Overview

Install

Server (Node, workers)

Browser

Context on a check

Polling and realtime

Failure modes

Next

​Overview

​Install

​Server (Node, workers)

​Browser

​Context on a check

​Polling and realtime

​Failure modes

​Next

Overview

Install

Server (Node, workers)

Browser

Context on a check

Polling and realtime

Failure modes

Next