SDKs

The TypeScript SDK ships in @shipeasy/sdk with conditional exports for Node, Shipeasy, Bun, Deno, and the browser. Bundlers pick the right build automatically; you can also import the explicit subpath if you want to be unambiguous.

Other languages have first-party adapters or community ports — see Ruby, Python & Go below.

Server SDK

Use this on your backend (Node, Workers, Bun, Deno, Next.js Server Components, etc.). The server SDK polls flag and experiment blobs in the background and evaluates locally — there is no per-request network call from your code.

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

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

configure() is idempotent — call it from the framework entry point that runs once per cold start (Next.js root layout.tsx, an Express app initialiser, your Worker fetch handler). The optional attributes transform maps your user object onto the Shipeasy attribute map used by every bound Client.

If you need to override the env or base URL (rare — defaults are correct for almost everyone), pass env / baseUrl to configure({ apiKey, env, baseUrl }).

Evaluating a feature flag

const flags = new Client(currentUser);
const enabled = flags.getFlag("new-checkout-flow");

Bind a Client to the user once, then read with no per-call user argument. getFlag() is synchronous — the rule set lives in process memory. The attributes available to targeting rules come from the attributes transform you passed to configure() — see User attributes for the full guide.

Reading a dynamic config

const pricing = flags.getConfig<{ base: number; currency: string }>("pricing");
const base = pricing?.base ?? 9.99;

Configs are typed via the optional generic. Always provide a fallback — your code should never crash because the SDK hasn't initialised yet.

Logging an event

flags.track("u_4f2a", "purchase", { value: 49.99, sku: "SHIRT-L-BLUE" });

track() is fire-and-forget. Events are batched and sent to /collect on the Shipeasy edge.

Resolving an experiment

const result = flags.getExperiment<{ color: "blue" | "green" }>(
  "checkout-button-color",
  { color: "blue" }, // defaultParams returned when not in experiment
);

if (result.inExperiment) {
  // result.group       e.g. "control" | "variant_a"
  // result.params.color
}

Assignment is deterministic by user_id. The first call for a user queues an exposure event that the daily analysis pipeline reads.

Translating a label

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

const greeting = i18n.t("home.hero.greeting", "Welcome back");

The i18n.t() function is part of the same SDK — no separate i18n init. Configuration happens once via the same shipeasy() call.

Browser SDK

Use this in the browser (Vite, Webpack, Next.js client, plain HTML). The browser SDK manages an anonymous_id cookie, fetches an evaluation bundle on init, and batches event uploads with navigator.sendBeacon on page hide.

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

configure({
  clientKey: import.meta.env.VITE_SHIPEASY_CLIENT_KEY ?? "",
  attributes: (u) => ({ user_id: u.id, plan: u.plan }),
});

const flags = new Client(currentUser);
await flags.ready();

if (flags.getFlag("new-checkout-flow")) {
  // …
}

flags.track("checkout_viewed", { source: "nav" });

Server-side rendering bootstrap

For Next.js / Remix / SvelteKit, configure() once at startup, then bind a Client to the request user and read flags, configs, experiments, killswitches, and SSR i18n strings directly:

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

configure({ apiKey: process.env.SHIPEASY_SERVER_KEY ?? "" });

const flags = new Client({ user_id: session?.user?.id });

if (flags.getFlag("new-checkout-flow")) {
  // render the new flow
}

The server-rendered evaluation lands on window.__SE_BOOTSTRAP for the client SDK to pick up — no flicker. Configure the client with configure({ clientKey }) and the bootstrap auto-hydrates before your first read.

Framework usage

Shipeasy ships a single SDK — @shipeasy/sdk — that works from plain JavaScript. Every API (getFlag, getConfig, getExperiment, i18n.t, track) is callable directly from React, Vue, Svelte, Angular, or vanilla JS without any framework-specific wrapper.

import { useEffect, useState } from "react";
import { configure, Client, i18n } from "@shipeasy/sdk/client";

configure({
  clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY ?? "",
  attributes: (u) => ({ user_id: u.id }),
});

const flags = new Client(currentUser);

function CheckoutButton() {
  const [enabled, setEnabled] = useState(() => flags.getFlag("new-checkout-flow"));
  useEffect(() => {
    const onChange = () => setEnabled(flags.getFlag("new-checkout-flow"));
    window.addEventListener("se:override:change", onChange);
    return () => window.removeEventListener("se:override:change", onChange);
  }, []);
  return <button>{i18n.t("checkout.cta", "Pay")}</button>;
}

The browser SDK dispatches the se:override:change event whenever a re-poll updates the cached blob or the devtools overlay flips an override. Wrap that listener in whatever reactivity primitive your framework provides (Vue's onMounted + onUnmounted, Svelte's onMount, Angular's ngOnInit, etc.).

A note on vanilla JS

Every Shipeasy SDK API works from plain JavaScript. You can drop the SDK into a plain <script> tag, an Astro island, an HTMX page, or a vanilla TS app, and every primitive — feature flags, configs, experiments, i18n — works without any framework.

React Native & mobile

Use the server build in React Native — the client build assumes a DOM:

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

Provide a stable anonymous_id — for example a UUID stored in AsyncStorage. The SDK has zero DOM dependencies in this build and works fine in the Hermes engine.

For native iOS and Android, use the JS SDK from the React Native bridge or call the same /sdk/* endpoints directly from Swift/Kotlin — the wire format is documented at Reference → SDK protocol.

Ruby

A Ruby gem is published as shipeasy-sdk on RubyGems:

require "shipeasy-sdk"

Shipeasy.configure do |c|
  c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY")
  c.attributes = ->(u) { { user_id: u.id, plan: u.plan } }
end

flags = Shipeasy::Client.new(current_user)
if flags.get_flag("new-checkout-flow")
  # …
end

The gem mirrors the JS API surface. Polling, evaluation, exposure events, and i18n all behave the same.

Rails

In a Rails app, drop the Shipeasy.configure block above into config/initializers/shipeasy.rb and you're done — the gem auto-mounts i18n_head_tags, i18n_inline_data, i18n_script_tag, and i18n_t view helpers via a Railtie. In plain Ruby (Sinatra, Hanami, scripts) the Rails surface is skipped automatically.

Python & Go

In closed beta. Same wire format, same mental model. Reach out on the dashboard if you want early access.

import shipeasy

shipeasy.configure(
    api_key=os.environ["SHIPEASY_SERVER_KEY"],
    attributes=lambda u: {"user_id": u.id, "plan": u.plan},
)

flags = shipeasy.Client(current_user)
if flags.get_flag("new-checkout-flow"):
    ...

shipeasy.Configure(shipeasy.Options{
    APIKey: os.Getenv("SHIPEASY_SERVER_KEY"),
})

flags := shipeasy.NewClient(currentUser)
if flags.GetFlag("new-checkout-flow") {
    // ...
}

DevTools overlay

Add ?shipeasy=1 to any URL on a site running the browser SDK and a debugging overlay appears. You can inspect every feature flag, every config, every label, and override values locally — no rule changes, no redeploys, scoped to your browser only.

import { loadDevtools } from "@shipeasy/sdk/client";

if (process.env.NODE_ENV !== "production") loadDevtools();

Useful for QA, dogfooding new variants, walking a customer through what they should be seeing, and inspecting the runtime variables a label or config is using.