Quickstart

Check your first flag in under a minute.

1. Get your server key

In the dashboard, open Settings → API keys and copy the server key:

ck_srv_prod_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

Keep it in an environment variable. Never put it in browser code — the SDK requires a server key and refuses the publishable ck_client_… key at startup. The key also picks the environment: production key, production rules.

2. Install

pnpm

pnpm add @lucerna-dev/gates-node @lucerna-dev/identity

npm

npm install @lucerna-dev/gates-node @lucerna-dev/identity

bun

bun add @lucerna-dev/gates-node @lucerna-dev/identity

3. Use it

Create one client when your server starts and share it everywhere — like a database connection:

import { createGates } from "@lucerna-dev/gates-node";

export const gates = createGates({
  serverKey: process.env.LUCERNA_GATES_KEY!,
});

await gates.ready(); // wait for your rules to load

Then say who the user is and check gates anywhere:

import { createIdentity } from "@lucerna-dev/identity";

// one identity per request — who is this check for?
const identity = createIdentity({ apiKey: process.env.LUCERNA_SERVER_KEY! });
identity.identify({ userId: user.id });
identity.trait("plan", user.plan);

// Feature flag → true / false
if (gates.flag("new_billing", identity.current())) {
  // show the new billing page
}

// Kill switch → false means the path is killed
if (!gates.switch("payments")) {
  return res.status(503).json({ error: "payments_paused" });
}

// Experiment → variant name, or null if the user isn't in it
const variant = gates.experiment("checkout_test", identity.current());

Checks are instant — no network call — and they never throw. Changes you make in the dashboard reach the SDK within 10 seconds.

4. On shutdown

process.on("SIGTERM", () => gates.close());

That's it. Next: the Node SDK reference.

Running on Cloudflare Workers, or prefer asking the server per call instead of a background refresh? See remote evaluation.