Node.js SDK

Use @squasher-ai/node in Node.js services, queue workers, scripts, and AWS Lambda functions. This page is tested with version 0.5.0 on Node.js 26.

What the SDK captures

Source	Captured
Uncaught exceptions and unhandled rejections	Yes, after you call `installGlobalHandlers()`.
Errors in Express, Fastify, Hono, and others	Yes, when you call `captureError` in the framework error handler.
AWS Lambda handler errors	Yes, when you wrap the handler in `withAwsLambda`.
Errors that you catch	Yes, when you call `captureError`.
Messages	Yes, when you call `captureMessage`.

Install the SDK

npm install @squasher-ai/node

The package is ESM only. Add your ingest key and project ID to the environment of your service:

.env

SQUASHER_API_KEY=sq_pk_...
SQUASHER_PROJECT_ID=...

To get both values, see Create an ingest key.

Initialize the SDK

Call init once, when the process starts, before the rest of your app code runs.

src/index.ts

import { init, installGlobalHandlers } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
  resourceAttributes: { "service.name": "checkout-api" },
});

installGlobalHandlers();

installGlobalHandlers() captures uncaught exceptions and unhandled promise rejections. After an uncaught exception, it sends the error, waits up to 5 seconds, and ends the process with exit code 1. resourceAttributes is optional. Set service.name when one project gets data from more than one service. Set environment to production in production: automatic AI triage runs only on issues from that environment.

Capture framework errors

Call captureError in the error handler of your framework. The second argument is optional. It adds your own fields to the event.

Express
Fastify
Hono

src/app.ts

import express, { type NextFunction, type Request, type Response } from "express";
import { captureError } from "@squasher-ai/node";

const app = express();

// Add the error handler after all routes.
app.use(async (error: Error, req: Request, res: Response, _next: NextFunction) => {
  await captureError(error, { url: req.originalUrl, method: req.method });
  res.status(500).json({ error: "Internal server error" });
});

src/app.ts

import Fastify from "fastify";
import { captureError } from "@squasher-ai/node";

const app = Fastify();

app.setErrorHandler(async (error, request, reply) => {
  await captureError(error as Error, { url: request.url, method: request.method });
  return reply.status(500).send({ error: "Internal server error" });
});

src/app.ts

import { Hono } from "hono";
import { captureError } from "@squasher-ai/node";

const app = new Hono();

app.onError(async (error, c) => {
  await captureError(error, { url: c.req.url, method: c.req.method });
  return c.json({ error: "Internal server error" }, 500);
});

To add context to every later event, call setUser({ id: "user_42" }) or setTag("region", "us-east-1"). The SDK sends the user ID and the tags with each event.

Wrap AWS Lambda handlers

Wrap the handler in withAwsLambda. When the handler throws, the wrapper sends the error with the request ID and function name, then throws it again. After each invocation, it waits for the SDK to send queued events.

src/handler.ts

import { init, withAwsLambda } from "@squasher-ai/node";

const client = init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: "production",
});

export const handler = withAwsLambda(client, async (event: { orderId: string }) => {
  await processOrder(event.orderId); // If this throws, Squasher captures it.
  return { statusCode: 200 };
});

The wrapper waits at most 1 second, and it stops 100 ms before the Lambda time limit. To change these limits, pass a third argument: { flushTimeoutMs: 500, remainingTimeReserveMs: 150 }. The wrapper needs no Lambda layer or extension.

Send a test error

Run this script once with the same environment variables:

scripts/squasher-test.ts

import { captureError, flush, init } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: "development",
});

await captureError(new Error("Squasher test error"));
await flush();

The SDK sends events in batches, every 5 seconds or when 25 events are queued. flush() sends them now, so a short script does not exit first. Then select Issues in the sidebar of your project. The test error is at the top of the list. If it does not appear, see Troubleshooting.

Send queued events at shutdown

A long-running service can lose the events that are still in the queue when it stops. Call close() when the process gets a stop signal. It sends the queued events, waiting up to 5 seconds.

src/index.ts

import { close } from "@squasher-ai/node";

process.on("SIGTERM", () => {
  void close().finally(() => process.exit(0));
});

Options

Option	Default	Description
`apiKey`	Required	Your ingest key. An empty string turns the SDK off: it sends nothing.
`projectId`	Required	Your project ID.
`environment`	None	The environment name, for example `production`.
`release`	Detected	The release name. See Releases.
`resourceAttributes`	None	Fields for every event, for example `{ "service.name": "checkout-api" }`.
`beforeSend`	None	A function that gets each event before it is sent. Return the event to send it, or `null` to drop it.
`sampling`	Send all	Rates from 0 to 1: `successRate`, `errorRate`, `slowRate`, and `slowThresholdMs` (1000).
`batchSize`	`25`	The number of queued events that starts a send.
`flushIntervalMs`	`5000`	The longest time between sends, in milliseconds.
`maxRetries`	`3`	Retries after a network error or a retryable HTTP status.
`maxBreadcrumbs`	`50`	Breadcrumbs kept in memory. Squasher does not store them.
`localEventSink`	`false`	`true` writes each event, after `beforeSend`, to `.squasher/events/<date>.jsonl` for local debugging.
`debug`	`false`	Log SDK activity to the console. `SQUASHER_DEBUG=true` also turns it on. Debug mode does not sample.
`endpoint`	`https://ingest.squasher.ai`	The ingest URL.

sampling treats events at warning level and above as errors, so errorRate applies to them. Events are never sampled out when their user ID is in alwaysSampleUserIds or their release is in alwaysSampleReleases.

Releases

When you do not set release, the SDK reads the first valid value from these environment variables: SQUASHER_RELEASE, VERCEL_GIT_COMMIT_SHA, RAILWAY_GIT_COMMIT_SHA, RENDER_GIT_COMMIT, FLY_MACHINE_VERSION, GITHUB_SHA, then npm_package_name and npm_package_version.

Limits

init throws when you call it a second time, and when apiKey or projectId is undefined. To run without Squasher in local development, pass an empty string.
After an HTTP 401 response, the SDK logs Invalid API key and stops sending events until the process restarts.
After an HTTP 429 response, the SDK waits once, up to 8 seconds, and then drops the batch.
The SDK sends breadcrumbs, but Squasher does not store them.
Stack traces point at the files that Node.js runs. If you bundle your code, upload source maps for the release so the issue page shows the original files.

Give the setup to a coding agent

Copy this prompt into your coding agent to install the SDK the same way:

Install @squasher-ai/node in this Node.js service. In the entry file, before other app code, call init
with apiKey from process.env.SQUASHER_API_KEY, projectId from process.env.SQUASHER_PROJECT_ID, and
environment from process.env.NODE_ENV, then call installGlobalHandlers(). In the framework error
handler, await captureError(error, { url, method }). For AWS Lambda, wrap each handler with
withAwsLambda(client, handler). On SIGTERM, await close() before the process exits. Verify with one
captureError(new Error("Squasher test error")) followed by await flush().

Next steps

Pino transport

Send Pino logs to the same project.

Winston transport

Send Winston logs to the same project.

Upload source maps

Store source maps for each release.

Read AI triage

Learn what the triage summary tells you.

Get started

Guides

What the SDK captures

Install the SDK

Initialize the SDK

Capture framework errors

Wrap AWS Lambda handlers

Send a test error

Send queued events at shutdown

Options

Releases

Limits

Give the setup to a coding agent

Next steps

Pino transport

Winston transport

Upload source maps

Read AI triage

​What the SDK captures

​Install the SDK

​Initialize the SDK

​Capture framework errors

​Wrap AWS Lambda handlers

​Send a test error

​Send queued events at shutdown

​Options

​Releases

​Limits

​Give the setup to a coding agent

​Next steps

Pino transport

Winston transport

Upload source maps

Read AI triage

What the SDK captures

Install the SDK

Initialize the SDK

Capture framework errors

Wrap AWS Lambda handlers

Send a test error

Send queued events at shutdown

Options

Releases

Limits

Give the setup to a coding agent

Next steps