Node.js

Install npm install @blipit/node

@blipit/node captures uncaught exceptions and unhandled promise rejections on its own, adds handlers for Express and Fastify, and ships logs and login attempts with the same key. Use the secret key; it stays on the server. From 0.3 it also has one-line setup for Koa, Hono and NestJS, and a wrapper for AWS Lambda style handlers.

Paste it into Claude Code, Cursor or any AI coding assistant. It carries the steps and the code. In app.blipit.io, API keys, the same prompt comes with your key filled in.
Video: Install Blipit in any stack, from 1:07

1Install

sh
npm install @blipit/node

2Get your keys

Sign in at app.blipit.io and open API keys in the sidebar, then your project. Every project has two keys. The public key starts with blipit_pk_: it goes in browser and app code, can only send events, and is safe for anyone to see. The secret key starts with blipit_sk_: it stays on your server or in Odoo, never in a browser, because it can also read and change issues. The secret key is shown only once, right after it is created, so copy it then; if you lose it, press Create a new secret key, and the old one stops working at once. Some SDKs also need the project id, shown on the same page.

API keys in app.blipit.io: the public key (blipit_pk_) for browser code and the secret key (blipit_sk_) for servers and Odoo.
API keys in app.blipit.io: the public key (blipit_pk_) for browser code and the secret key (blipit_sk_) for servers and Odoo.
A new secret key is shown once. Copy it now: it is stored hashed and cannot be shown again.
A new secret key is shown once. Copy it now: it is stored hashed and cannot be shown again.

3Keep the key in the environment

Node uses the secret key. Put it in an environment variable, never in code: locally in a .env file that Node 20.6 and later load with --env-file, in production in your host's environment or secret settings (Fly secrets, Docker, systemd, Render, Vercel). Restart the process after changing it.

.env
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key
sh
node --env-file=.env --import ./instrument.mjs server.mjs

4Keep keys out of git

Keep keys in environment variables or your host's secret settings, never in code you commit, and add your .env files to .gitignore. A public key in a web page is normal. If a secret key ever ends up in git, a public page, a screenshot or a chat, open API keys, press Create a new secret key, and paste the new key wherever the old one was used: the old key stops working straight away.

.gitignore
.env
.env.local
.env.*.local

5Initialise first

Put this in a file that runs before your app, and import it first.

instrument.mjs
import * as Blipit from "@blipit/node";

Blipit.init({
  key: process.env.BLIPIT_SECRET_KEY,
  environment: process.env.NODE_ENV,
  release: process.env.RELEASE,
  serverName: "api",
});

6Express, Fastify, Koa, Hono or NestJS

Add the handler after your routes so handled and unhandled errors both reach Blipit, with the request's method, URL and user agent. Koa, Hono and NestJS take one line each: Koa's middleware goes first, Hono's before the routes. They report errors with a status of 500 or above. Requests then show on the Pulse page by route, such as GET /users/:id, instead of one line per URL.

js
import "./instrument.mjs";
import * as Blipit from "@blipit/node";
import express from "express";

const app = express();
app.get("/", (req, res) => res.send("ok"));
app.use(Blipit.expressErrorHandler());
app.listen(3000);
Fastify
await app.register(Blipit.fastifyPlugin());
Koa
app.use(Blipit.koaMiddleware());
Hono
app.use(Blipit.honoMiddleware());
NestJS
app.useGlobalInterceptors(Blipit.nestInterceptor());

7Serverless: AWS Lambda and Vercel

Serverless hosts pause the function as soon as it answers, and Lambda does not run Node's HTTP server, so wrap the handler. wrapHandler records the request (API Gateway, function URL and load balancer events by method and route, other events by function name), reports errors and sends everything before the handler returns; it waits only when there is something to send, at most 2 seconds. traceRequest does the same for any handler that takes a Request. On Vercel the data goes out after the response through waitUntil, so nothing is delayed. In Next.js use withBlipit (see the Next.js guide).

js
import * as Blipit from "@blipit/node";

export const handler = Blipit.wrapHandler(async (event, context) => {
  return { statusCode: 200, body: "ok" };
});
traceRequest
export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };

8Manual capture, logs and login attempts

js
Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%", "warning");
Blipit.setUser({ id: "user-42" });
Blipit.log.info("order placed", { order_id: 42 });
Blipit.captureSecurity({ kind: "login_failed", actor: email, ip, userAgent, outcome: "bad_password" });
await Blipit.flush();

9Dependencies and server health

From 0.2 the SDK also records your database and outside-service calls, and your server's CPU, memory and event loop. See the Dependencies and Server health guides; tracesSampleRate, tracing: false and metrics: false control it.

10Check it works

Open Issues in app.blipit.io. The first event appears within a few seconds, grouped into an issue, and the people in charge get an email.

js
Blipit.captureMessage("Hello from Node");

Good to know

  • On an uncaught exception the SDK flushes pending events, then exits with code 1; override with onFatal.
  • captureConsole: true turns console.log and friends into log lines shipped to the Logs page.
  • Check the installed version with npm ls @blipit/node (or pnpm list @blipit/node). pnpm 11 waits a day before it installs a new release (minimum-release-age), so on release day pnpm add quietly installs the previous version; to get the new one at once, run pnpm add @blipit/node@<version> --config.minimum-release-age=0.
  • Keeping Blipit up to date: the Keeping Blipit up to date guide (docs.blipit.io/updates) explains the update banner, the emails for important releases, the notice in your development console and the update command for this platform.
  • One project per app and platform: each project picks its platform when it is created (Android, iOS, React Native, Flutter, Web, Backend or Odoo), and Blipit refuses data from any other platform with a clear error, so an iOS app and an Android app need two projects with two keys. Releases, versions, crash rates and store builds differ per platform, so mixing them in one project makes all of them wrong. A Web project also takes the server side of the same web app (the Next.js server or Node), and a React Native or Flutter project also takes its own native Android and iOS crash reports.

Stuck? Email support@blipit.io. Keys and the project id for each project are under API keys in app.blipit.io.