Install bugstack for JavaScript and TypeScript

Install the bugstack JavaScript SDK with npm install bugstack-sdk, wire up ErrorCaptureClient.init, and start capturing errors in under five minutes.

Compatibility

Node.js 18+ TypeScript 5+ (optional) Next.js 14+ Express 4.x / 5.x

Install

Install the SDK with your preferred package manager:

npm

npm install bugstack-sdk

pnpm

pnpm add bugstack-sdk

yarn

yarn add bugstack-sdk

Initialize

Call ErrorCaptureClient.init() once at application startup:

import { ErrorCaptureClient } from 'bugstack-sdk';

ErrorCaptureClient.init({
  apiKey: process.env.BUGSTACK_API_KEY,
  endpoint: process.env.BUGSTACK_ENDPOINT || 'https://api.bugstack.ai/capture',
});

Next.js (App Router)

Initialize in lib/bugstack.ts

// lib/bugstack.ts
import { ErrorCaptureClient } from 'bugstack-sdk';

export const bugstack = ErrorCaptureClient.init({
  apiKey: process.env.BUGSTACK_API_KEY!,
  endpoint: process.env.BUGSTACK_ENDPOINT || 'https://api.bugstack.ai/capture',
});

Wrap route handlers with withErrorCapture

// app/api/users/route.ts
import { withErrorCapture } from 'bugstack-sdk';

export const GET = withErrorCapture(async (request: Request) => {
  const users = await db.user.findMany();
  return Response.json(users);
});

Dynamic route with typed params

// app/api/users/[id]/route.ts
import { withErrorCapture } from 'bugstack-sdk';

export const GET = withErrorCapture(async (
  request: Request,
  { params }: { params: { id: string } }
) => {
  const user = await db.user.findUnique({ where: { id: params.id } });
  if (!user) return Response.json({ error: 'Not found' }, { status: 404 });
  return Response.json(user);
});

Express

Option A: Error handler middleware (recommended)

const express = require('express');
const { initBugStack, errorHandler } = require('bugstack-sdk');

const app = express();

initBugStack({
  apiKey: process.env.BUGSTACK_API_KEY,
});

app.get('/', (req, res) => {
  res.send('Hello World');
});

// Add bugstack error handler after all routes
app.use(errorHandler());

app.listen(3000);

Option B: Wrap individual handlers

const { wrapFunction, initBugStack } = require('bugstack-sdk');

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY });

app.get('/users', wrapFunction(async (req, res) => {
  const users = await db.user.findMany();
  res.json(users);
}));

Generic Node.js

const {
  initBugStack,
  installGlobalHandlers,
  captureError,
  wrapFunction,
  createErrorCapture,
} = require('bugstack-sdk');

// Initialize
initBugStack({ apiKey: process.env.BUGSTACK_API_KEY });

// Capture uncaught exceptions and unhandled rejections
installGlobalHandlers();

// Manual capture
try {
  riskyOperation();
} catch (err) {
  captureError(err, { context: 'manual-catch' });
}

// Wrap any async function
const safeOperation = wrapFunction(async () => {
  await riskyOperation();
});

// Create a reusable error capture instance
const capture = createErrorCapture({ metadata: { service: 'worker' } });

Environment Variables

Variable	Description	Required
`BUGSTACK_API_KEY`	Your project API key from the dashboard	Yes
`BUGSTACK_ENDPOINT`	Custom endpoint URL (defaults to https://api.bugstack.ai/capture)	No
`BUGSTACK_PROJECT_ID`	Explicit project identifier	No
`NODE_ENV`	Used as the default `environment` value	No

TypeScript Types

The SDK ships with full TypeScript definitions. Key exported types:

import type {
  ErrorCaptureConfig,
  CapturedError,
  StackFrame,
  RouteOptions,
  RouteContext,
  ErrorReportPayload,
  SourceContext,
} from 'bugstack-sdk';

Configuration Reference

Option	Type	Default	Description
`apiKey`	string	—	Required. Your bugstack API key.
`endpoint`	string	`'https://api.bugstack.ai/capture'`	Error capture endpoint URL.
`projectId`	string	`undefined`	Explicit project identifier.
`environment`	string	`process.env.NODE_ENV`	Environment name (production, staging, etc.).
`enabled`	boolean	`true`	Master kill switch for error capture.
`captureRequestBody`	boolean	`false`	Include request body in error reports.
`captureQueryParams`	boolean	`true`	Include query parameters in error reports.
`captureHeaders`	boolean	`false`	Include request headers in error reports.
`maxBodySize`	number	`10240`	Maximum request body size in bytes to capture.
`redactFields`	string[]	`['password', 'secret', 'token', 'authorization']`	Field names to redact from captured data.
`metadata`	Record<string, unknown>	`{}`	Arbitrary metadata attached to every error report.
`timeout`	number	`5000`	HTTP timeout in milliseconds for sending reports.
`deduplicationWindow`	number	`60000`	Window in ms to deduplicate identical errors.
`debug`	boolean	`false`	Log internal SDK activity to console.
`shouldCapture`	(error: Error) => boolean	`undefined`	Filter function to decide if an error should be captured.
`beforeSend`	(payload: ErrorReportPayload) => ErrorReportPayload \| null	`undefined`	Transform or drop error payloads before sending.

Next Steps

Start capturing JavaScript errors now

bugstack catches runtime errors in production, writes the fix, runs your CI, and opens a tested pull request — in under 2 minutes.

Start Free Trial Book a Demo