JavaScript SDK

Capture production errors automatically in your Express and Next.js applications.

Installation

$ npm install bugstack-sdk

Quick Start: Express

javascript

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

const app = express();

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

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

// bugstack automatically captures unhandled errors
app.listen(3000);

Quick Start: Next.js

typescript

// app/layout.tsx
import { initBugStack } from 'bugstack-sdk';

// Initialize bugstack once at the app root
initBugStack({ apiKey: process.env.BUGSTACK_API_KEY! });

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

What the SDK captures

The bugstack JavaScript SDK hooks into Node's global error channels the moment initBugStack() runs. It listens for uncaughtException, unhandledRejection, Express error-middleware failures, and Next.js server action errors. Every captured event carries the full stack trace, the request path, the HTTP method, response status (if known), and a fingerprint used for deduplication.

Capture is asynchronous. The SDK enqueues errors in-memory and flushes them on a short interval, so reporting never blocks your event loop or your response to a user. If bugstack's endpoint is unreachable, the SDK retries up to five times with exponential backoff before dropping the event silently.

Framework adapters

The SDK auto-detects Express and Next.js and installs the appropriate hooks. For Express, bugstack registers a terminal error-handling middleware ((err, req, res, next)) after your own middleware stack, so thrown errors inside route handlers are captured without a try/catch wrapper. For Next.js App Router, bugstack instruments the server runtime to capture errors thrown in server components, route handlers, and server actions.

For Pages Router projects, the SDK patches getServerSideProps and getStaticProps return paths, and API routes are instrumented via a wrapper you can opt into with withBugStack(handler). Worker threads, child processes, and serverless runtimes (Vercel, AWS Lambda, Cloudflare Workers) are supported — just call initBugStack() at the top of your entry file.

Configuration

apiKey (required) — your project API key from the dashboard. Use process.env.BUGSTACK_API_KEY.
environment (optional) — label for filtering: production, staging, development. Defaults to NODE_ENV.
release (optional) — git commit SHA or semver. Attached to every event for regression tracking across deploys.
sampleRate (optional) — 0–1 float. Defaults to 1.0. Lower for extremely high-volume services.
beforeSend (optional) — callback to scrub PII or drop events. Return null to skip an event.
ignoreErrors (optional) — array of regex or string matchers. Useful for bot-traffic noise and known harmless warnings.

Common JavaScript errors bugstack fixes

These are the most frequent error patterns the SDK captures in production Node and browser runtimes. Each link opens a step-by-step fix guide:

Troubleshooting

No events in the dashboard? Confirm the API key is set and non-empty at process start (console.log(!!process.env.BUGSTACK_API_KEY)). In serverless, make sure initBugStack() runs on cold start, not inside a handler.

Events captured but no fix PR? The GitHub App must be installed on the repo you want fixes in. Visit the dashboard → Repositories to confirm. Fix generation also requires that the error's source file lives in a connected repo.

Too many duplicate events? The SDK deduplicates by fingerprint within a 24-hour rolling window. If you're seeing counts that look high, check your beforeSend hook isn't mutating the error message (which changes the fingerprint).

See the full JavaScript installation guide for advanced setup (source maps, custom transports, monorepo wiring).

Data and privacy

The SDK sends the error message, stack trace, and request metadata (path, method, status, timing) to the bugstack API. It does not send request bodies, response bodies, cookies, or authorization headers unless you explicitly include them via beforeSend. The GitHub App reads only the files named in the stack trace — not your full repository. All data is encrypted in transit and at rest, and you can delete project data at any time from the dashboard. See the data handling doc for the detailed retention policy.

Versioning and compatibility

The SDK follows semver. Breaking changes ship behind a major version bump. Node 18+ is supported; Node 16 reaches EOL on our side when upstream EOL hits. Next.js 13+ is supported (both App Router and Pages Router); Next.js 12 is on maintenance support. Express 4 and 5 are both supported. The SDK has no native dependencies and no compile step — npm install bugstack-sdk is the whole install.

Source Code

View the full source code, report issues, and contribute on GitHub.

← Back to Documentation