@shipeasy/sdk

@shipeasy/sdk (TypeScript)

The Shipeasy SDK for feature flags, dynamic configs, kill switches, A/B experiments, metric tracking, and SSR/i18n — for Node, Next.js, and Cloudflare Workers. Server-key only on the server; the browser uses its own client key.

📚 Full documentation: https://shipeasy-ai.github.io/sdk/ — also browsable under docs/. This README is generated from those docs.

🤖 Using an AI agent?

This SDK ships an installable agent skill — a copy-paste-ready guide to configure() + new Client(user), testing, experiments, error reporting, and more, with links the agent can pull for deeper docs:

• Skill: docs/skill/SKILL.md · raw: https://shipeasy-ai.github.io/sdk/skill/SKILL.md
• Install it (ships with the package — no network): npx shipeasy-skill install → .claude/skills/shipeasy-typescript/SKILL.md (or via the Shipeasy CLI: shipeasy docs skill --sdk typescript --install)

Humans: you can copy that skill straight into your own project's agent skills directory (e.g. .claude/skills/shipeasy-typescript/SKILL.md) so your coding agent always uses the correct Shipeasy patterns. Every doc page and snippet is also fetchable by URL — start from the manifest at https://shipeasy-ai.github.io/sdk/manifest.json.

Install

npm install @shipeasy/sdk
# or
pnpm add @shipeasy/sdk
# or
yarn add @shipeasy/sdk

Per-framework setup (Next.js / Express / Cloudflare Workers) and the anon-id middleware are on the Installation page.

Quickstart — configure() once, then new Client(user) per request

import { configure, Client } from "@shipeasy/sdk/server"; // or /client

configure({ apiKey: process.env.SHIPEASY_SERVER_KEY!,
            attributes: (u: MyUser) => ({ user_id: u.id, plan: u.plan }) });

const flags = new Client(currentUser);
if (flags.getFlag("new_checkout")) { /* ship it */ }

Constructing new Client(user) before configure() throws.

Documentation

Page	What
Overview	The configure() + new Client(user) model.
Installation	Install, frameworks (Next / Express / Workers), configure() wiring.
Configuration	Keys, attributes, one-shot vs poll, every option.
Feature flags	getFlag, getFlagDetail, defaults.
Dynamic configs	getConfig, typed decode, defaults.
Kill switches	getKillswitch, named switches.
Experiments	getExperiment, logExposure, track.
Internationalization	SSR bootstrap + i18n loader tags.
Error reporting	see() structured error reporting.
Testing	configureForTesting / configureForOffline, overrides.
OpenFeature	ShipeasyProvider (OpenFeature server provider).
react native devtools	The SDK ships a shake-to-open devtools overlay for React Native / Expo apps at feature…
browser devtools	The in-browser devtools overlay ships inside the SDK, sharing one headless core (@shipe…
Advanced	Anon-id middleware, private attributes, sticky bucketing, SSR.

Copy-paste snippets live under docs/snippets/ (release · metrics · i18n · ops); an installable agent skill is at docs/skill/SKILL.md.

Testing

For unit tests, swap the live configure() for configureForTesting() — a drop-in sibling with no network, ever (no SDK key required). It replaces the active configuration with a network-free engine, seeds the values your code should see, and is read through the ordinary new Client(user). In this mode the rules never fetch, track() is a no-op, assign() logs no exposure, and telemetry is off — your tests never touch the network.

import { configureForTesting, Client, clearOverrides } from "@shipeasy/sdk/server"; // or /client

// Seed everything the code under test should see (no key, no network):
configureForTesting({
  flags: { new_checkout: true },
  configs: { upload_limits: { max_uploads: 50 } },
});

const flags = new Client({ user_id: "u_1" }); // construct once per callsite
flags.getFlag("new_checkout");                 // true
flags.getConfig("upload_limits");              // { max_uploads: 50 }

clearOverrides(); // reset every seeded override back to the empty-blob default

More — the on-the-spot override helpers and a working example snapshot file — on the Testing page.

License

See LICENSE. Evaluation is tested against the cross-language MurmurHash3 vectors in experiment-platform/04-evaluation.md.