Quickstart
Five steps. You end with a control plane and a dashboard, one flag, and an app that changes the moment you toggle it. About five minutes.
You need Node 22+ and Docker running. In development featurekit starts a throwaway Postgres container for you, so there's nothing to install or configure.
Two processes
| The control plane | Your app | |
|---|---|---|
| What it is | FeaturekitServer: API, dashboard, propagation | Your existing service, holding an SDK |
| File in this guide | server.js | app.js |
| Talks to | Postgres | The control plane, once at start and then over a stream |
| On a flag check | Not involved | Answers from memory |
In production the control plane can live inside a service you already run. Here they're two files so you can see the split. Steps are tagged server, app or dashboard.
-
Install setup The server package, plus the helper that starts Postgres in Docker during development.
mkdir flags-demo && cd flags-demo npm init -y && npm pkg set type=module npm i featurekit-server npm i -D @testcontainers/postgresql # dev only -
Start the control plane server One flag, defined in code. It's created on first start and left alone after that.
import { FeaturekitServer } from "featurekit-server"; const server = new FeaturekitServer({ port: 3000, flags: { project: { key: "acme", name: "Acme" }, environment: { key: "development", name: "Development", isProduction: false }, flags: [ { key: "new-checkout", name: "New checkout flow", kind: "boolean", variations: [{ name: "off", value: false }, { name: "on", value: true }], config: { enabled: true, offVariation: "off", fallthroughVariation: "on" }, }, ], }, env: { FEATUREKIT_ADMIN_EMAIL: "you@acme.com", FEATUREKIT_ADMIN_PASSWORD: process.env.FEATUREKIT_ADMIN_PASSWORD, }, }); await server.start(); console.log(`dashboard: ${server.url}/admin`);FEATUREKIT_ADMIN_PASSWORD=choose-a-long-one node server.jsThe first start pulls the Postgres image and runs the migrations. The two
FEATUREKIT_ADMIN_*values create your first dashboard account. The password must be at least 12 characters. -
Create a server key dashboard Your app authenticates with a key that belongs to one environment.
Open
http://127.0.0.1:3000/admin, sign in, and go to Keys → New key. Pick server. Copy the key: it's shown once.Server keys are secretsA server key gets every rule in the environment. Keep it on your servers. Browsers and apps use a client key, which only gets answers.
-
Read the flag app
ready()loads the rules once. Everyget()after that is in memory.import { FeaturekitSDK } from "featurekit-server/sdk"; const flags = new FeaturekitSDK({ sdkKey: process.env.FEATUREKIT_SDK_KEY, baseUrl: "http://127.0.0.1:3000", }); await flags.ready({ timeoutMs: 5_000 }); setInterval(() => { console.log(flags.get("new-checkout", { key: "user-1" }, false)); }, 1_000);FEATUREKIT_SDK_KEY=fk_srv_… node app.js # true # trueThe third argument is the default: what you get if featurekit is unreachable, the flag doesn't exist, or something is wrong. It's required on purpose.
-
Flip it dashboard The change is pushed to the SDK over a stream. No restart, no redeploy.
Leave
app.jsrunning and turnnew-checkoutoff in the dashboard. Within a second the output changes:true true false falseOr do it from the terminal with the kill switch, using a personal access token from Settings:
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/development/flags/new-checkout/off \ -H "Authorization: Bearer $FEATUREKIT_TOKEN"
The full example
examples/basic-example runs the control plane, a website and an Expo app on one live stream, across all four flag kinds:
git clone https://github.com/devkitshq/featurekit && cd featurekit
npm install && npm run build
node examples/basic-example/server/server.js
node examples/basic-example/server/swap.js # in another terminal: flips flags live
If something goes wrong
| You see | Why | Do |
|---|---|---|
starting Postgres in Docker needs @testcontainers/postgresql | No databaseUrl, and the dev helper isn't installed | npm i -D @testcontainers/postgresql, or pass databaseUrl |
could not start a development container | Docker isn't running | Start Docker, or pass databaseUrl |
get() always returns the default | The SDK has no snapshot: wrong key, wrong URL, or ready() timed out | Check flags.state. Pass onError to see why. |
401 WRONG_TIER | A client key on the server SDK, or the reverse | Server SDK takes fk_srv_, client SDK takes fk_clt_ or fk_mob_ |