flagkit-sdk

TypeScript SDK for FlagKit — a lightweight, self-hostable feature flag service.

Zero dependencies. Works in Node.js, Deno, Bun, and edge runtimes.

Install

npm install flagkit-sdk

Quick Start

import { FlagKit } from 'flagkit-sdk'

const flags = new FlagKit({
  apiKey: 'fk_...',
  baseUrl: 'https://your-api.railway.app',
})

if (await flags.isEnabled('new-checkout', { userId: 'user_123' })) {
  // show new checkout
}

API

new FlagKit(options)

Create a new client instance.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your FlagKit API key | | baseUrl | string | required | Base URL of your FlagKit API | | ttl | number | 30000 | Cache TTL in milliseconds |

flags.isEnabled(key, context?)

Evaluate whether a feature flag is enabled.

Parameters:

| Name | Type | Description | |------|------|-------------| | key | string | Flag key to evaluate (e.g. "new-checkout") | | context.userId | string? | User ID for targeting rules | | context.environment | string? | "production", "staging", or "development" |

Returns: Promise<boolean>

Caching

Results are cached in memory with a configurable TTL (default 30s).

| Scenario | Behavior | |----------|----------| | Cache hit (fresh) | Returns cached value immediately | | Cache miss | Calls API, caches result, returns it | | API error + stale cache | Returns last cached value | | API error + no cache | Returns false (safe default) |

Evaluation Logic

Flags use targeting rules that evaluate top-to-bottom (first match wins):

• Allowlist — if userId is in the list, flag is enabled
• Percentage rollout — deterministic via consistent hashing (fnv32(flagKey + userId) % 100), same user always gets the same result

If the flag is globally disabled, evaluation short-circuits to false.

TypeScript

Full type definitions are included. Key exports:

import { FlagKit } from 'flagkit-sdk'
import type { FlagKitOptions, EvalContext, EvalResult } from 'flagkit-sdk'

License

MIT