Koa integration guide

Add Bugsnag to your Koa projects to automatically capture and report errors in production.

New to Bugsnag? Create an account

Installation

npm

Install Bugsnag and the Bugsnag / Koa integration from the npm registry using npm or yarn:

npm install --save @bugsnag/js @bugsnag/plugin-koa
# or
yarn add @bugsnag/js @bugsnag/plugin-koa

Basic configuration

This documentation is for version 7 of the Bugsnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Depending on which module system you are using, you’ll need to include Bugsnag in one of the following ways:

// commonjs/node-style require
const Bugsnag = require('@bugsnag/js')
const BugsnagPluginKoa = require('@bugsnag/plugin-koa')

// ES module-style import
import Bugsnag from '@bugsnag/js'
import BugsnagPluginKoa from '@bugsnag/plugin-koa'

To start Bugsnag with the Koa integration, import it and pass it along with your API key to Bugsnag.start as configuration:

Bugsnag.start({
  apiKey: 'YOUR_API_KEY',
  plugins: [BugsnagPluginKoa],
  otherOptions: value
})

And in the part of your application where the Koa server is configured, obtain and use the Koa middleware:

const app = new Koa()
const middleware = Bugsnag.getPlugin('koa')

// This must be the first piece of middleware in the stack.
// It can only capture errors in downstream middleware
app.use(middleware.requestHandler)

/* all other middleware and application routes go here */

// This handles any errors that Koa catches
app.on('error', middleware.errorHandler)

For information on values that can be set in the configuration object, see configuration options.

TypeScript support

Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import any of the top-level @bugsnag/* packages.

Reporting unhandled errors

After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be automatically reported.

Unhandled errors in Koa routes will be reported with information about the request.

Reporting handled errors

Sometimes it is useful to manually notify Bugsnag of a problem. To do this, call Bugsnag.notify() with an Error object. For example:

try {
  something.risky()
} catch (e) {
  Bugsnag.notify(e)
}

See reporting handled errors for more information.

As well as capturing and reporting unhandled errors, the requestHandler middleware attaches a request-scoped Bugsnag client to ctx.bugsnag. This means that if you encounter an error in route or piece of middleware, you can call ctx.bugsnag.notify(err) which will include information about the request in the error report. For example:

app.use(async (ctx, next) => {
  const product = await db.products.find(ctx.request.query.productId)
  if (product.discontinued) {

    // This report will include detail about the request, plus anything we attach here
    ctx.bugsnag.notify(
      new Error('Attempted to purchase discontinued product'),
      function (event) {
        event.addMetadata('product', product)
      }
    )

    ctx.body = renderPurchaseError(product)
  } else {
    ctx.body = renderInvoice(product)
  }
})

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • Request info (if relevant and available)
  • Device time
  • Hostname
  • Release stage (production, beta, staging, etc)

Custom diagnostics

Custom data can be capture by adding metadata to the Bugsnag client, for all errors, or an individual event.

The following adds a map of data to the “company” tab on the Bugsnag dashboard for all captured events:

Bugsnag.addMetadata('company', {
  name: "Acme Co.",
  country: "uk"
})

For additional options on attaching custom metadata, see customizing error reports.

Leaving breadcrumbs

Breadcrumbs are not yet supported on Node.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

You can set the user information of an error report using the user configuration property when Bugsnag starts or via an onError callback.

Bugsnag.start({
  onError: function (event) {
    event.setUser('3', 'bugs.nag@bugsnag.com', 'Bugs Nag')
  }
})

For information on doing so, see Adding user data.

Tracking releases

Configure your app version to see the release that each error was introduced in.

Bugsnag.start({ appVersion: '4.10.0' })

Then set up a build tool integration to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Session tracking

Sessions are reported in Node.js every time a request is served if you are using one of the server integrations:

  • @bugsnag/plugin-express
  • @bugsnag/plugin-restify
  • @bugsnag/plugin-koa

A summary of sessions recorded will be periodically sent to Bugsnag.

For more information about manually controlling session tracking, see Capturing sessions.

Next steps

  • View @bugsnag/js, the library powering Bugsnag for Node.js, on GitHub
  • Get support for your questions and feature requests