Skip to main content
← All platforms
Quickstart

Node.js

The server SDK for Node.js: track events from your backend and evaluate flags and experiments per user.

Package
@sheepit-ai/server
Runs on
Node 20+

Get an API key

Don't have an account yet? Create one, free. Then open Settings → API Keys in the dashboard and copy a secret key (lp_sec_…). It has full access to your project, so keep it on your server.

Install

bash
npm install @sheepit-ai/server

Initialize and send your first event

sheepit.ts
import { SheepitServer } from "@sheepit-ai/server";

export const sheepit = new SheepitServer({
  apiKey: process.env.SHEEPIT_SECRET_KEY!, // lp_sec_... — never ship it to a browser
  appVersion: process.env.GIT_SHA,
});

sheepit.track("invoice_paid", { amount_cents: 4900 }, "user_123");

// Serverless: flush before the function returns, or buffered events are lost.
await sheepit.flush();

Read a flag and an experiment

ts
// import { sheepit } from "./sheepit";
const enabled = await sheepit.flag("new_billing", { userId: "user_123" }, false);

// userId is required on the server.
const { variant } = await sheepit.experiment("pricing_page", "user_123");

Check that it worked

Run the script, then open Events in the dashboard. The invoice_paid event shows up within about a minute.

Worth knowing

  • Use a secret key and keep it on the server. Never put it in a NEXT_PUBLIC_ variable.
  • Events are buffered and sent every 5 seconds. In a serverless function, await flush() before you return, or the buffered events are lost.
  • On the server, experiment() records an exposure event but flag() does not. Flag values are cached per user (cacheTtl, 60 seconds by default).
  • Traits passed to flag() are not used for targeting yet. Server-side targeting uses what the user's own devices reported.
  • In Next.js, getSheepit() from @sheepit-ai/server/nextjs gives you a shared client configured from SHEEPIT_SECRET_KEY.
  • Requires Node 20 or later. Edge runtimes are not supported.
  • Self-hosted install? Add apiUrl: "https://<your-install>/api" to the config. The docs inside your install's dashboard show the exact value.
Node.js quickstart | Sheepit