@checkgate/edge
Evaluate Checkgate feature flags at the edge — Cloudflare Workers, Deno Deploy, Fastly, Vercel Edge, Fly.io.
A tiny, runtime-agnostic edge evaluator. It owns the edge concern — pull a
flag snapshot from your Checkgate server, cache it with a TTL and optional
stale-while-revalidate, survive origin outages by keeping the last-known-good
snapshot — and delegates the actual evaluation to an injected engine. In
production that engine is the shared @checkgate/web WebAssembly core, so edge
evaluation is identical to every other Checkgate SDK. No re-implemented
rule / rollout / segment / prerequisite logic to drift.
Zero dependencies. Works anywhere fetch exists.
Install
npm install @checkgate/edgeUse
import { CheckgateEdge } from '@checkgate/edge'
import { createWasmCore } from '@checkgate/web/core'
// Wrangler compiles a .wasm import into a WebAssembly.Module. On Node (Next.js
// server) and in the browser, call createWasmCore() with no argument instead.
import wasmModule from '@checkgate/web/dist/checkgate_bg.wasm'
const edge = new CheckgateEdge({
serverUrl: 'https://flags.your-domain.com',
sdkKey: env.CHECKGATE_SDK_KEY, // environment-scoped SDK key (Bearer)
core: await createWasmCore(wasmModule), // the WASM evaluation engine
ttlSeconds: 30, // re-fetch the snapshot at most this often
staleWhileRevalidateSeconds: 60, // serve stale + refresh in background
})
// On each request (fast: in-memory on a warm isolate):
await edge.ensureFresh({ waitUntil: (p) => ctx.waitUntil(p) })
const showIt = edge.isEnabled('new-homepage', userKey)
const color = edge.getValue('checkout-color', userKey, {}, 'blue')API
| Member | Description |
|---|---|
new CheckgateEdge({ serverUrl, sdkKey, core, ttlSeconds?, staleWhileRevalidateSeconds?, fetchImpl?, now?, snapshotPath? }) |
Construct. core is the injected engine. |
refresh() |
Fetch the snapshot and load it into the core. Concurrent calls are de-duplicated. Fails open to last-known-good. |
ensureFresh({ waitUntil? }) |
Load if never loaded; serve from cache within the TTL; serve stale + background-refresh within the SWR window; block-refresh beyond it. |
isEnabled(key, userKey, attrs?) / getValue(key, userKey, attrs?, default?) / getVariant(key, userKey, attrs?) |
Delegate to the core. |
isLoaded / flagCount / lastLoadedAt / ageMs() |
Introspection. |
Design
- Fail-open. If a refresh can't reach origin, the previous snapshot keeps serving — an origin blip never takes your flags down. The first load has nothing to fall back to, so it surfaces the error.
- De-duplicated refresh. A burst of concurrent
ensureFresh()calls triggers at most one snapshot fetch. - Injected
core,fetch, and clock. That's what makes it dependency-free and fully unit-tested in plain Node (npm test) — no WASM build or edge runtime required to verify the caching/resilience logic.
Examples
examples/cloudflare-worker— per-request edge evaluation on Cloudflare Workers, with a Cron Trigger keeping the snapshot warm.examples/fly— deploy the full Checkgate server multi-region on Fly.io.
Part of Checkgate — the self-hosted feature-flag platform.