Install on Node

The @sankofa/node package is the official server-side SDK for Node.js. It focuses on Catch — error capture, breadcrumbs, transactions, and profiling — with first-class Express and Fastify integration via dedicated subpath imports. Server-side flag and config evaluation is not built in; the SDK accepts optional readFlagSnapshot / readConfigSnapshot callbacks so captured error events can include flag context.

Requirements

• Node.js 18+ (we test 18, 20, and 22)
• TypeScript 5+ (optional but recommended)
• ESM and CommonJS are both supported

1. Install the package

npm install @sankofa/node

pnpm add @sankofa/node

yarn add @sankofa/node

bun add @sankofa/node

2. Initialize at process start

Call Sankofa.init once, as early as possible — typically in your server entry file before any imports that might throw.

import { Sankofa } from "@sankofa/node";

Sankofa.init({
apiKey: process.env.SANKOFA_KEY!,
endpoint: "https://api.sankofa.dev",
release: process.env.RELEASE_SHA ?? "dev",
environment: process.env.NODE_ENV ?? "development",
});

Common init options

3. Wire your framework

The Node SDK ships subpath exports for Express and Fastify so the same package serves both.

import express from "express";
import { Sankofa } from "@sankofa/node";
import { sankofaRequestHandler, sankofaErrorHandler } from "@sankofa/node/express";

Sankofa.init({ apiKey: process.env.SANKOFA_KEY! });

const app = express();

// Must be the first middleware — captures request context for every event.
app.use(sankofaRequestHandler());

app.get("/", (req, res) => {
Sankofa.track("homepage_visited", {}, { distinctId: req.user?.id ?? "anon" });
res.send("ok");
});

// Must be the last middleware — captures uncaught errors.
app.use(sankofaErrorHandler());

import Fastify from "fastify";
import { Sankofa } from "@sankofa/node";
import { sankofaPlugin } from "@sankofa/node/fastify";

Sankofa.init({ apiKey: process.env.SANKOFA_KEY! });

const app = Fastify({ logger: true });
await app.register(sankofaPlugin);

app.get("/", async (request) => {
Sankofa.track("homepage_visited", {}, { distinctId: request.user?.id ?? "anon" });
return { ok: true };
});

await app.listen({ port: 3000 });

import { Sankofa } from "@sankofa/node";

Sankofa.init({ apiKey: process.env.SANKOFA_KEY! });

process.on("uncaughtException", (err) => {
Sankofa.captureException(err);
});

await Sankofa.track("worker_started", { version: process.version });

4. Verify the install

await Sankofa.track("install_check", { from: "node-quickstart" });

Open app.sankofa.dev → Live events. You should see the event with a node source label and the runtime version captured under default properties.

What's next