Core concepts

​

Overview

​

Where things live

Organization            fieldkit
└── Project             web-app          ← flags are defined here, once
    ├── Environment     development      ← each environment has its own
    ├── Environment     staging            enabled state, rules, fallthrough,
    └── Environment     production         SDK keys, and snapshot
            └── Snapshot  v42            ← everything the SDK needs to evaluate

​

How a flag gets to your app

 shipd.config.ts          you write flag definitions
       │
       ▼
   shipd push             the CLI syncs definitions
       │
       ▼
 Control plane            stores definitions + state (dashboard edits land here too)
       │  publishes on every change
       ▼
   Snapshot               one JSON document per environment
       │
       ▼
 Edge (CDN)               serves the snapshot to SDKs, notifies them of changes
       │
       ▼
 SDK in your app          keeps the snapshot in memory
       │
       ▼
 shipd.isEnabled(…)       evaluated locally — no network call

1. Define. TypeScript or Go definitions declare which flags exist and their types; The CLI reads Go definitions directly. It’s reviewed in pull requests like any other code.
2. Sync. shipd push compares the file with shipd and applies the difference. It also writes TypeScript types or Go accessors for your flags.
3. Control. In the dashboard you decide what each flag serves per environment: on or off, rules for specific users, percentage rollouts.
4. Publish. Every change produces a new snapshot version for the affected environment.
5. Deliver. The SDK downloads the snapshot at startup, then refreshes it every 30 seconds, or on a WebSocket notification in TypeScript streaming clients.
6. Evaluate. TypeScript’s isEnabled, getVariant, getNumber, and getJson, and Go’s IsEnabled, GetVariant, GetNumber, and GetJSON, read the in-memory snapshot and never throw. See SDK benchmarks for measured boolean evaluation latency and throughput.

​

How a value is chosen

No snapshot yet?            → your code's defaults[key]
Flag not in snapshot?       → your code's defaults[key]
Flag disabled here?         → the snapshot's default, which shipd derives from the fallthrough; rules are skipped
Rule matches the context?   → that rule's serve  (rules are checked top to bottom)
Otherwise                   → the fallthrough

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

client.IsEnabled("new-checkout", shipd.EvaluationContext{
    UserID: "usr_8f2k19", Attributes: map[string]any{"plan": "pro", "country": "US"},
})

​

Two kinds of credentials

​

What this means in practice

• Your app doesn’t wait on shipd. Flag checks are in memory. If shipd is down, the SDK keeps the last snapshot it had, or serves your defaults.
• Code owns what exists; the dashboard owns what’s served. Add or change flag definitions and run shipd push. To archive a flag, remove its definition and run shipd push --prune after reviewing the plan. Turn them on, target users, and roll out in the dashboard.
• Environments share definitions, not state. Adding a flag adds it everywhere. Turning it on in staging doesn’t touch production.
• Always pass defaults. They are what your users get before the first snapshot arrives and whenever shipd can’t be reached.

​

Go deeper

• Architecture: control plane, data plane, and realtime updates
• Local evaluation: the hot path and failure modes
• Environments: production protection and per-environment state
• Snapshots: the document the SDK evaluates
• Glossary: every term, defined once