# Node.js quickstart

Source: https://www.sheepit.ai/docs/sdks/node

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

- Package: [@sheepit-ai/server](https://www.npmjs.com/package/@sheepit-ai/server)
- Runs on: Node 20+

## 1. Get an API key

Don't have an account yet? [Create one, free](https://www.sheepit.ai/signup). 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.

## 2. Install

```bash
npm install @sheepit-ai/server
```

## 3. Initialize and send your first event

`sheepit.ts`:

```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();
```

## 4. 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");
```

## 5. 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.