@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 is delivered as a hosted script, not as an npm dependen… | | 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 Rollouts & bucketing.