# 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

-   [Privacy & Data Handling](/docs/privacy)
-   [How bugstack Works Under the Hood](/docs/how-it-works)
-   [JavaScript SDK Overview](/for/javascript)

## 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](https://dashboard.bugstack.ai/login) [Book a Demo](/demo)