Sentry Node.js / Bun / Deno SDK

NestJS? Use sentry-nestjs-sdk instead — it uses @sentry/nestjs with NestJS-native decorators and filters. Next.js? Use sentry-nextjs-sdk instead — it handles the three-runtime architecture (browser, server, edge).

Note: SDK versions below reflect current Sentry docs at time of writing (@sentry/node ≥10.42.0, @sentry/bun ≥10.42.0, @sentry/deno ≥10.42.0). Always verify against docs.sentry.io/platforms/javascript/guides/node/ before implementing.

Phase 1: Detect

Run these commands to identify the runtime, framework, and existing Sentry setup:

# Detect runtime
bun --version 2>/dev/null && echo "Bun detected"
deno --version 2>/dev/null && echo "Deno detected"
node --version 2>/dev/null && echo "Node.js detected"

# Detect existing Sentry packages
cat package.json 2>/dev/null | grep -E '"@sentry/'
cat deno.json deno.jsonc 2>/dev/null | grep -i sentry

# Detect Node.js framework
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@hapi/hapi"|"koa"|"@nestjs/core"|"connect"'

# Detect Bun-specific frameworks
cat package.json 2>/dev/null | grep -E '"elysia"|"hono"'

# Detect Deno frameworks (deno.json imports)
cat deno.json deno.jsonc 2>/dev/null | grep -E '"oak"|"hono"|"fresh"'

# Detect module system (Node.js)
cat package.json 2>/dev/null | grep '"type"'
ls *.mjs *.cjs 2>/dev/null | head -5

# Detect existing instrument file
ls instrument.js instrument.mjs instrument.ts instrument.cjs 2>/dev/null

# Detect logging libraries
cat package.json 2>/dev/null | grep -E '"winston"|"pino"|"bunyan"'

# Detect cron / scheduling
cat package.json 2>/dev/null | grep -E '"node-cron"|"cron"|"agenda"|"bull"|"bullmq"'

# Detect AI / LLM usage
cat package.json 2>/dev/null | grep -E '"openai"|"@anthropic-ai"|"@langchain"|"@vercel/ai"|"@google/generative-ai"'

# Check for companion frontend
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

What to determine:

Phase 2: Recommend

Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

• ✅ Error Monitoring — always; captures unhandled exceptions, promise rejections, and framework errors
• ✅ Tracing — automatic HTTP, DB, and queue instrumentation via OpenTelemetry

Optional (enhanced observability):

• ⚡ Logging — structured logs via Sentry.logger.*; recommend when winston/pino/bunyan or log search is needed
• ⚡ Profiling — continuous CPU profiling (Node.js only; not available on Bun or Deno)
• ⚡ AI Monitoring — OpenAI, Anthropic, LangChain, Vercel AI SDK; recommend when AI/LLM calls detected
• ⚡ Crons — detect missed or failed scheduled jobs; recommend when node-cron, Bull, or Agenda is detected
• ⚡ Metrics — custom counters, gauges, distributions; recommend when custom KPIs needed

Recommendation logic:

Propose: "I recommend setting up Error Monitoring + Tracing. Want me to also add Logging or Profiling?"

Phase 3: Guide

Runtime: Node.js

Option 1: Wizard (Recommended for Node.js)

You need to run this yourself — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal:

npx @sentry/wizard@latest -i node

It handles login, org/project selection, SDK installation, instrument.js creation, and package.json script updates.

Once it finishes, come back and skip to Verification.

If the user skips the wizard, proceed with Option 2 (Manual Setup) below.

Option 2: Manual Setup — Node.js

Install

npm install @sentry/node --save
# or
yarn add @sentry/node
# or
pnpm add @sentry/node

Create the Instrument File

CommonJS (instrument.js):

// instrument.js — must be loaded before all other modules
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,

  // 100% in dev, lower in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Capture local variable values in stack frames
  includeLocalVariables: true,

  enableLogs: true,
});

ESM (instrument.mjs):

// instrument.mjs — loaded via --import flag before any other module
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  includeLocalVariables: true,
  enableLogs: true,
});

Start Your App with Sentry Loaded First

CommonJS — add require("./instrument") as the very first line of your entry file:

// app.js
require("./instrument"); // must be first

const express = require("express");
// ... rest of your app

ESM — use the --import flag so Sentry loads before all other modules (Node.js 18.19.0+ required):

node --import ./instrument.mjs app.mjs

Add to package.json scripts:

{
  "scripts": {
    "start": "node --import ./instrument.mjs server.mjs",
    "dev": "node --import ./instrument.mjs --watch server.mjs"
  }
}

Or via environment variable (useful for wrapping existing start commands):

NODE_OPTIONS="--import ./instrument.mjs" npm start

Framework Error Handlers

Register the Sentry error handler after all routes so it can capture framework errors:

Express:

const express = require("express");
const Sentry = require("@sentry/node");

const app = express();

// ... your routes

// Add AFTER all routes — captures 5xx errors by default
Sentry.setupExpressErrorHandler(app);

// Optional: capture 4xx errors too
// Sentry.setupExpressErrorHandler(app, {
//   shouldHandleError(error) { return error.status >= 400; },
// });

app.listen(3000);

Fastify:

const Fastify = require("fastify");
const Sentry = require("@sentry/node");

const fastify = Fastify();

// Add BEFORE routes (unlike Express!)
Sentry.setupFastifyErrorHandler(fastify);

// ... your routes

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

Koa:

const Koa = require("koa");
const Sentry = require("@sentry/node");

const app = new Koa();

// Add as FIRST middleware (catches errors thrown by later middleware)
Sentry.setupKoaErrorHandler(app);

// ... your other middleware and routes

app.listen(3000);

Hapi (async — must await):

const Hapi = require("@hapi/hapi");
const Sentry = require("@sentry/node");

const server = Hapi.server({ port: 3000 });

// ... your routes

// Must await — Hapi registration is async
await Sentry.setupHapiErrorHandler(server);

await server.start();

Connect:

const connect = require("connect");
const Sentry = require("@sentry/node");

const app = connect();

// Add BEFORE routes (like Fastify and Koa)
Sentry.setupConnectErrorHandler(app);

// ... your middleware and routes

require("http").createServer(app).listen(3000);

NestJS — has its own dedicated skill with full coverage:

Use the sentry-nestjs-sdk skill instead. NestJS uses a separate package (@sentry/nestjs) with NestJS-native constructs: SentryModule.forRoot(), SentryGlobalFilter, @SentryTraced, @SentryCron decorators, and GraphQL/Microservices support. Load that skill for complete NestJS setup.

Vanilla Node.js http module — wrap request handler manually:

const http = require("http");
const Sentry = require("@sentry/node");

const server = http.createServer((req, res) => {
  Sentry.withIsolationScope(() => {
    try {
      // your handler
      res.end("OK");
    } catch (err) {
      Sentry.captureException(err);
      res.writeHead(500);
      res.end("Internal Server Error");
    }
  });
});

server.listen(3000);

Framework error handler summary:

Runtime: Bun

No wizard available for Bun. Manual setup only.

Install

bun add @sentry/bun

Create instrument.ts (or instrument.js)

// instrument.ts
import * as Sentry from "@sentry/bun";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

Start Your App with --preload

bun --preload ./instrument.ts server.ts

Add to package.json:

{
  "scripts": {
    "start": "bun --preload ./instrument.ts server.ts",
    "dev": "bun --watch --preload ./instrument.ts server.ts"
  }
}

Bun.serve() — Auto-Instrumentation

@sentry/bun automatically instruments Bun.serve() via JavaScript Proxy. No extra setup is required — just initialize with --preload and your Bun.serve() calls are traced:

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

Framework Error Handlers on Bun

Bun can run Express, Fastify, Hono, and Elysia. Use the same @sentry/bun import and the @sentry/node error handler functions (re-exported by @sentry/bun):

import * as Sentry from "@sentry/bun";
import express from "express";

const app = express();
// ... routes
Sentry.setupExpressErrorHandler(app);
app.listen(3000);

Bun Feature Support

Runtime: Deno

No wizard available for Deno. Manual setup only. Requires Deno 2.0+. Deno 1.x is not supported. Use npm: specifier. The deno.land/x/sentry registry is deprecated.

Install via deno.json (Recommended)

{
  "imports": {
    "@sentry/deno": "npm:@sentry/[email protected]"
  }
}

Or import directly with the npm: specifier:

import * as Sentry from "npm:@sentry/deno";

Initialize — Add to Entry File

// main.ts — Sentry.init() must be called before any other code
import * as Sentry from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",

  sendDefaultPii: true,
  tracesSampleRate: Deno.env.get("DENO_ENV") === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

// Your application code follows
Deno.serve({ port: 8000 }, (req) => {
  return new Response("Hello from Deno!");
});

Unlike Node.js and Bun, Deno does not have a --preload or --import flag. Sentry must be the first import in your entry file.

Required Deno Permissions

The SDK requires network access to reach your Sentry ingest domain:

deno run \
  --allow-net=o<ORG_ID>.ingest.sentry.io \
  --allow-read=./src \
  --allow-env=SENTRY_DSN,SENTRY_RELEASE \
  main.ts

For development, --allow-all works but is not recommended for production.

Deno Cron Integration

Deno provides native cron scheduling. Use denoCronIntegration for automatic monitoring:

import * as Sentry from "@sentry/deno";
import { denoCronIntegration } from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",
  integrations: [denoCronIntegration()],
});

// Cron is automatically monitored
Deno.cron("daily-cleanup", "0 0 * * *", () => {
  // cleanup logic
});

Deno Feature Support

For Each Agreed Feature

Load the corresponding reference file and follow its steps:

For each feature: read the reference file, follow its steps exactly, and verify before moving on.

Verification

After setup, verify Sentry is receiving events:

// Add temporarily to your entry file or a test route, then remove
import * as Sentry from "@sentry/node"; // or @sentry/bun / @sentry/deno

Sentry.captureException(new Error("Sentry test error — delete me"));

Or trigger an unhandled exception:

// In a route handler or startup — will be captured automatically
throw new Error("Sentry test error — delete me");

Then check your Sentry Issues dashboard — the error should appear within ~30 seconds.

Verification checklist:

Config Reference

Sentry.init() Core Options

Graceful Shutdown

Flush buffered events before process exit — important for short-lived scripts and serverless:

process.on("SIGTERM", async () => {
  await Sentry.close(2000); // flush with 2s timeout
  process.exit(0);
});

Environment Variables

Source Maps (Node.js)

Readable stack traces in production require source map upload. Use @sentry/cli or the webpack/esbuild/rollup plugins:

npm install @sentry/cli --save-dev

# Create a Sentry auth token at sentry.io/settings/auth-tokens/
# Set in .env.sentry-build-plugin (gitignore this file):
SENTRY_AUTH_TOKEN=sntrys_eyJ...

Add upload step to your build:

{
  "scripts": {
    "build": "tsc && sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload ./dist"
  }
}

Phase 4: Cross-Link

After completing backend setup, check for companion services:

# Frontend companion
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

# Other backend services
ls ../go.mod ../requirements.txt ../Gemfile 2>/dev/null

If a frontend, framework-specific SDK, or other backend is found, suggest the matching skill:

Dedicated JavaScript framework skills (prefer these over generic node-sdk):

Frontend companions:

Other backend companions:

Connecting frontend and backend with the same DSN or linked projects enables distributed tracing — stack traces that span your browser, API server, and database in a single trace view.

Troubleshooting