You are an expert in integrating Bugsnag for error tracking and crash reporting.

## Key Points

- Enable `autoTrackSessions` and use the stability score dashboard to make release decisions based on real crash data.
- Use `enabledReleaseStages` to prevent development and test errors from polluting production data.
- Add structured metadata via `addMetadata` rather than cramming information into the error message string.
- Set `appVersion` on every build so errors are correlated with specific releases and you can track regressions.
- Use `onError` callbacks to redact PII and sensitive fields before events are sent.
- Not setting `appVersion`, which makes it impossible to determine which release introduced a bug.
- Placing the Express error handler middleware before route definitions, causing it to never fire.
- Calling `Bugsnag.notify()` without the event callback, missing the opportunity to attach useful metadata.
- Leaving `autoTrackSessions` disabled and then wondering why the stability score shows no data.
- Uploading source maps with a mismatched `appVersion`, resulting in un-symbolicated stack traces.

## Quick Example

```bash
npm install @bugsnag/js @bugsnag/plugin-react
```

```bash
npm install @bugsnag/node
```

Bugsnag — Error Tracking

You are an expert in integrating Bugsnag for error tracking and crash reporting.

Core Philosophy

Overview

Bugsnag is a stability monitoring platform focused on application health and release quality. It automatically detects and groups errors, tracks stability scores per release, and supports over 50 platforms including web, mobile, and backend. Use Bugsnag when release stability metrics and mobile crash reporting are top priorities.

Setup & Configuration

JavaScript Browser

npm install @bugsnag/js @bugsnag/plugin-react

import Bugsnag from "@bugsnag/js";
import BugsnagPluginReact from "@bugsnag/plugin-react";
import React from "react";

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  plugins: [new BugsnagPluginReact()],
  appVersion: "1.2.0",
  releaseStage: process.env.NODE_ENV,
  enabledReleaseStages: ["production", "staging"],
});

const ErrorBoundary = Bugsnag.getPlugin("react").createErrorBoundary(React);

const App = () => (
  <ErrorBoundary>
    <MyApp />
  </ErrorBoundary>
);

Node.js

npm install @bugsnag/node

const Bugsnag = require("@bugsnag/node");

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  appVersion: "1.2.0",
  releaseStage: process.env.NODE_ENV,
});

Express Middleware

const express = require("express");
const Bugsnag = require("@bugsnag/node");
const BugsnagPluginExpress = require("@bugsnag/plugin-express");

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  plugins: [BugsnagPluginExpress],
});

const app = express();
const middleware = Bugsnag.getPlugin("express");

// Must be first middleware
app.use(middleware.requestHandler);

// Your routes here

// Must be last middleware
app.use(middleware.errorHandler);

Core Patterns

Error Capturing

// Notify Bugsnag of a caught error
try {
  riskyOperation();
} catch (error) {
  Bugsnag.notify(error);
}

// Notify with a callback to add metadata
Bugsnag.notify(error, (event) => {
  event.severity = "warning";
  event.addMetadata("order", { orderId: "abc-123", total: 49.99 });
});

Context and Breadcrumbs

// Leave a breadcrumb
Bugsnag.leaveBreadcrumb("User clicked checkout", {
  itemCount: 3,
  cartTotal: 49.99,
});

// Set context for the current scope
Bugsnag.setContext("checkout/payment");

User Identification

Bugsnag.setUser("user-42", "user@example.com", "Jane Doe");

// Or via the event callback
Bugsnag.notify(error, (event) => {
  event.setUser("user-42", "user@example.com", "Jane Doe");
});

Release Tracking

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  appVersion: "1.2.0",
});

# Upload source maps via CLI
npx bugsnag-source-maps upload-browser \
  --api-key YOUR_API_KEY \
  --app-version 1.2.0 \
  --directory ./dist

Source Maps with Webpack

const { BugsnagSourceMapUploaderPlugin } = require("webpack-bugsnag-plugins");

module.exports = {
  devtool: "source-map",
  plugins: [
    new BugsnagSourceMapUploaderPlugin({
      apiKey: "YOUR_API_KEY",
      appVersion: "1.2.0",
    }),
  ],
};

Advanced Features

Stability Score

Bugsnag calculates a per-release stability score (percentage of sessions without unhandled errors). Use this in CI/CD to gate rollouts — if stability drops below a threshold, halt the deploy.

Feature Flags Integration

Bugsnag.notify(error, (event) => {
  event.addFeatureFlags([
    { name: "new-checkout-flow", variant: "enabled" },
    { name: "dark-mode", variant: "control" },
  ]);
});

Session Tracking

Bugsnag.start({
  apiKey: "YOUR_API_KEY",
  autoTrackSessions: true, // default in browser SDK
});

// Manual session management
Bugsnag.startSession();
Bugsnag.pauseSession();
Bugsnag.resumeSession();

Custom Grouping

Bugsnag.notify(error, (event) => {
  event.groupingHash = "payment-timeout";
});

Best Practices

• Enable autoTrackSessions and use the stability score dashboard to make release decisions based on real crash data.
• Use enabledReleaseStages to prevent development and test errors from polluting production data.
• Add structured metadata via addMetadata rather than cramming information into the error message string.
• Set appVersion on every build so errors are correlated with specific releases and you can track regressions.
• Use onError callbacks to redact PII and sensitive fields before events are sent.

Common Pitfalls

• Not setting appVersion, which makes it impossible to determine which release introduced a bug.
• Placing the Express error handler middleware before route definitions, causing it to never fire.
• Calling Bugsnag.notify() without the event callback, missing the opportunity to attach useful metadata.
• Leaving autoTrackSessions disabled and then wondering why the stability score shows no data.
• Uploading source maps with a mismatched appVersion, resulting in un-symbolicated stack traces.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.