Quickstart

Initialise the SDK

Initialise once at boot. The server SDK polls flag updates in the background — no per-request cost, no fetch on the hot path.

import { configureShipeasy, flags } from "@shipeasy/sdk/server";

configureShipeasy({
  apiKey: process.env.SHIPEASY_SERVER_KEY!,
  
});

export const ready = flags.init();

Import this once from your entrypoint and await ready before serving the first request. After that, every flags.gate() call is synchronous and reads from in-process memory.

Create a gate

From the CLI:

shipeasy flags create new-checkout-flow --rollout 0

Or in the dashboard: Configs → Gates → New gate, name new-checkout-flow, leave the rollout at 0%. The default value is false — nobody sees the new path yet.

Naming conventions to save your future self pain:

• kebab-case: new-checkout-flow, not newCheckoutFlow.
• Describe the change, not the abstract feature: enable-redis-pool ages better than redis-pool.
• Prefix by area: checkout-, nav-, infra-. Makes deletion sweeps easy.

Gate your code

import { flags } from "@shipeasy/sdk/server";

export async function getCheckoutComponent(user) {
  if (flags.gate("new-checkout-flow", user)) {
    return import("./checkout/new");
  }
  return import("./checkout/legacy");
}

gate() is synchronous and reads from the in-process cache. Pass any user attributes you want available to targeting rules — at minimum { user_id }. The shape of user is just a plain object:

{
  user_id: "u_4f2a",      // required for deterministic bucketing
  plan: "pro",            // any attribute your rules want
  country: "US",
  tenure_days: 142,
}

Test locally with overrides

Add yourself to the overrides list in the dashboard (Gate → Overrides → Always on, paste your user_id). The flag returns true for you and false for everyone else — no rollout math involved.

If you have the browser DevTools overlay loaded, you can also force a value with a query param:

https://app.local/?shipeasy_gate_new-checkout-flow=true

That's persisted in localStorage and survives reloads until you toggle it off.

Roll it out gradually

Bump the rollout from 0% → 5% → 25% → 100% over a few hours, watching your error rate and p95.

shipeasy flags rollout new-checkout-flow --percent 5
shipeasy flags rollout new-checkout-flow --percent 25
shipeasy flags rollout new-checkout-flow --percent 100

Bucketing is deterministic by user_id, so the same 5% always sees the new path. You won't see flicker as you bump the percentage — you only ever add users to the bucket, never reshuffle.

A safe schedule for an unknown-risk change:

0%   → enable rule + dogfood with overrides
1%   → 1 hour, watch error rate + p95
5%   → 4 hours
25%  → overnight
50%  → 1 day
100% → keep an eye on it for a week, then delete the flag

Killswitch (when something breaks)

If something goes wrong, flip the killswitch. It overrides every targeting rule and serves false everywhere within the SDK's next poll (default 30s, faster on Pro).

shipeasy flags disable new-checkout-flow --killswitch

Dashboard: toggle the red Killswitch chip on the gate row. The killswitch is a separate field from enabled, so flipping it preserves your targeting rules and rollout — re-enabling restores the full prior state.

Wire it into CI

Add a check that fails the build if you reference a flag that doesn't exist on the project:

- name: Validate flags
  run: shipeasy flags validate ./src

This catches typos (new-checkut-flow) and stale references after a flag has been deleted.