Star
Start here

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 planeYour app
What it isFeaturekitServer: API, dashboard, propagationYour existing service, holding an SDK
File in this guideserver.jsapp.js
Talks toPostgresThe control plane, once at start and then over a stream
On a flag checkNot involvedAnswers 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.

  1. 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
  2. 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.js

    The 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.

  3. 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 secrets

    A server key gets every rule in the environment. Keep it on your servers. Browsers and apps use a client key, which only gets answers.

  4. Read the flag app ready() loads the rules once. Every get() 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
          # true

    The 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.

  5. Flip it dashboard The change is pushed to the SDK over a stream. No restart, no redeploy.

    Leave app.js running and turn new-checkout off in the dashboard. Within a second the output changes:

    true
          true
          false
          false

    Or 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 seeWhyDo
starting Postgres in Docker needs @testcontainers/postgresqlNo databaseUrl, and the dev helper isn't installednpm i -D @testcontainers/postgresql, or pass databaseUrl
could not start a development containerDocker isn't runningStart Docker, or pass databaseUrl
get() always returns the defaultThe SDK has no snapshot: wrong key, wrong URL, or ready() timed outCheck flags.state. Pass onError to see why.
401 WRONG_TIERA client key on the server SDK, or the reverseServer SDK takes fk_srv_, client SDK takes fk_clt_ or fk_mob_

Next