---
title: Configuration
description: Complete configuration reference for Honeybadger's JavaScript library with all available options and settings.
url: https://docs.honeybadger.io/lib/javascript/reference/configuration/
---

## Configuration file (server-side only)

When using the JavaScript client in a Node.js environment, you can configure Honeybadger using a configuration file in your project’s root directory, such as `honeybadger.config.js` or `honeybadger.config.ts`. The configuration file should export an object with the configuration.

An example configuration file is shown below:

honeybadger.config.js

```javascript
module.exports = {
  apiKey: process.env.HONEYBADGER_API_KEY,
  environment: process.env.NODE_ENV,
  revision: process.env.HONEYBADGER_REVISION,
  // etc.
};
```

## Configuration options

All of the available configuration options are shown below:

```javascript
Honeybadger.configure({
  // Honeybadger API key (required)
  apiKey: "",


  // The revision of the current deploy
  revision: "",


  // Project root
  projectRoot: "http://my-app.com",


  // Environment
  environment: "production",


  // Defaults to the server's hostname in Node.js
  hostname: "badger01",


  // Environments which will not report data
  developmentEnvironments: ["dev", "development", "test"],


  // Override `developmentEnvironments` to explicitly enable/disable error reporting
  // reportData: true,


  // Key values to filter from request data. Matches are partial, so "password"
  // and "password_confirmation" will both be filtered
  filters: ["creditcard", "password"],


  // Tags to apply to every reported error. Accepts an array of strings or a
  // comma-separated string. See "Tagging errors".
  tags: [],


  // Component (optional)
  component: "",


  // Action (optional)
  action: "",


  // Should unhandled errors be reported?
  // This option uses `window.onerror` in browsers and `uncaughtException` in Node.js
  enableUncaught: true,


  // Executed after an uncaught exception is reported in Node.js.
  // See "Uncaught exceptions" in the Node.js integration guide.
  // afterUncaught: (error) => {},


  // Should unhandled Promise rejections be reported?
  enableUnhandledRejection: true,


  // Enable breadcrumbs collection
  breadcrumbsEnabled: true,


  // Insights instrumentation (off by default). `enabled` is the master switch;
  // `console` and `http` are ignored unless `enabled` is true.
  insights: {
    enabled: false,
    // Forward console logs to Honeybadger Insights
    console: false,
    // Emit request.handled events for inbound HTTP requests (server integrations)
    http: false,
  },


  // Event delivery controls for Insights
  events: {
    // How often to flush buffered events, in seconds
    dispatchIntervalSeconds: 10,
    // Flush when this many events are buffered
    bulkThreshold: 500,
    // Percentage of events to send (0–100)
    sampleRatePercentage: 100,
  },


  // Deprecated: use `insights.enabled` and `insights.console` instead.
  // Setting `eventsEnabled: true` auto-enables both (not `insights.http`) and
  // logs a deprecation warning. Explicit `insights` values win over the shim.
  // eventsEnabled: false,


  // Collector Host
  // If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io".
  endpoint: "https://api.honeybadger.io",


  // The maximum number of breadcrumbs to include with error reports
  maxBreadcrumbs: 40,


  // The maximum depth allowed in deeply-nested objects
  maxObjectDepth: 8,


  // The logger to use. Should behave like `console`
  logger: console,


  // Output Honeybadger debug messages to the logger
  debug: false,
});
```

The following additional options are available in **browser environments**:

```javascript
Honeybadger.configure({
  // Send notifications asynchronously
  async: true,


  // Endpoint to submit user feedback for errors. See "Collecting User Feedback".
  // If you are using our EU stack, this should be set to "https://eu-api.honeybadger.io/v2/feedback".
  userFeedbackEndpoint: "https://api.honeybadger.io/v2/feedback",


  // Limit the maximum number of errors the client will send to Honeybadger
  // after page load. Default is unlimited (undefined)
  maxErrors: 20,


  // Ignore errors that originate from browser extensions (chrome-extension://,
  // moz-extension://, safari-extension://, safari-web-extension://).
  // Errors filtered by this option do not count against `maxErrors`.
  ignoreBrowserExtensionErrors: false,


  // Enable breadcrumbs collection
  breadcrumbsEnabled: true,
  // You can also selectively configure these types of breadcrumbs:
  // breadcrumbsEnabled: {
  //   dom: true,
  //   network: true,
  //   navigation: true,
  //   console: true
  // }


  // Element attributes to prefer when naming elements in click breadcrumbs.
  // See "Naming elements in click breadcrumbs" below.
  breadcrumbsSelectorAttributes: ["data-hb-name"],
});
```

The following additional options are available in **serverless environments** (currently AWS Lambda):

```javascript
Honeybadger.configure({
  // Report a warning to Honeybadger when a Lambda function is about to reach
  // its configured time limit
  reportTimeoutWarning: true,


  // How close (in milliseconds) the function must get to the Lambda time
  // limit before the timeout warning is reported
  timeoutWarningThresholdMs: 50,
});
```

See [Timeout warning](https://docs.honeybadger.io/lib/javascript/integration/node/#timeout-warning) in the Node.js integration guide for details.

### Naming elements in click breadcrumbs

When you click an element, Honeybadger records a `ui.click` breadcrumb containing a CSS selector for that element. By default the selector is built from each element’s tag, id, and classes, which can be hard to read in apps that use utility CSS frameworks such as Tailwind:

```plaintext
body > div#root > main > div.flex.min-h-screen.flex-col.font-sans.antialiased > ...
```

To make these breadcrumbs legible, add a `data-hb-name` attribute to the elements you care about. When a clicked element — or one of its ancestors — has the attribute, its value replaces that element’s selector segment, and the nearest named ancestor anchors the selector, so everything above it is dropped. Given this markup:

```html
<div data-hb-name="deal-card">
  <h3 class="text-left font-semibold">Acme Corp</h3>
</div>
```

Clicking the heading records the selector `deal-card > h3.text-left.font-semibold` instead of the full chain from `<body>`.

Use `breadcrumbsSelectorAttributes` to reuse attributes you already have, such as the test IDs from your test suite. The first attribute in the list that is present on an element wins:

```javascript
Honeybadger.configure({
  breadcrumbsSelectorAttributes: ["data-hb-name", "data-testid"],
});
```

Set the option to `[]` to disable this behavior and always build selectors from tags, ids, and classes.

## Configuring with environment variables

Unlike some of our other client libraries, *honeybadger.js* does **not** automatically read configuration from environment variables; to use environment variables, you must configure Honeybadger like this:

```javascript
Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  environment: process.env.NODE_ENV,
  revision: process.env.HONEYBADGER_REVISION,
  // etc.
});
```

Note that `process.env` may not be available outside of Node.js by default (it depends on your JavaScript build system). For example, [in Webpack you need to use`environmentPlugin`](https://webpack.js.org/plugins/environment-plugin/) to make `process.env` keys available in source files.

## `beforeEvent` handlers

`beforeEvent` handlers run before each Insights event is sent to Honeybadger. Handlers may be synchronous or asynchronous. Return `false` (or a promise that resolves to `false`) to skip the event, or mutate the payload in place to change what is sent. See [Filtering events](https://docs.honeybadger.io/lib/javascript/insights/filtering-events/).

```javascript
Honeybadger.beforeEvent((event) => {
  if (event.event_type === "request.handled" && event.path === "/health") {
    return false;
  }
});
```

## `beforeBreadcrumb` handlers

`beforeBreadcrumb` handlers run before each breadcrumb is recorded, including the ones Honeybadger captures automatically. Handlers are synchronous. Return `false` to drop the breadcrumb, or mutate it in place to change what is recorded. See [Filtering breadcrumbs](https://docs.honeybadger.io/lib/javascript/errors/breadcrumbs/#filtering-breadcrumbs).

```javascript
Honeybadger.beforeBreadcrumb((breadcrumb) => {
  if (/\/telemetry\//.test(breadcrumb.metadata.url)) {
    return false;
  }
});
```

## `beforeNotify` handlers

`beforeNotify` handlers run before each notice (error report) is sent to Honeybadger. There are two cases this might be useful:

1. Filtering out unwanted error reports by returning `false` from a handler
2. Sanitizing or enhancing notice data before being sent to Honeybadger

### Usage examples

Sanitizing notice data:

```javascript
Honeybadger.beforeNotify((notice) => {
  if (/creditCard/.test(notice.url)) {
    notice.url = "[FILTERED]";
  }
});
```

Adding additional context to notice data:

```javascript
Honeybadger.beforeNotify((notice) => {
  notice.context.session_id = MyApp.sessionId;
});
```

Adding additional context to notice data from an async source:

```javascript
Honeybadger.beforeNotify(async (notice) => {
  notice.context.state = await MyApp.getState();
});
```

Skipping a notice:

```javascript
Honeybadger.beforeNotify((notice) => {
  if (/third-party-domain/.test(notice.stack)) {
    return false;
  }
});
```

## `afterNotify` handlers

`afterNotify` handlers run *after* each notice (error report) is sent to Honeybadger. Here are two cases where this is useful:

1. Displaying the ID of the Honeybadger notice to users
2. Handling errors if the Honeybadger API rejects the notice

### Usage examples

Log a URL to the error report in Honeybadger:

```javascript
Honeybadger.afterNotify((err, notice) => {
  if (err) {
    return console.log(`Honeybadger notification failed: ${err}`);
  }
  console.log(
    `Honeybadger notice: https://app.honeybadger.io/notice/${notice.id}`,
  );
});
```

An `afterNotify` handler can also be attached to a single error report:

```javascript
Honeybadger.notify("testing", {
  afterNotify: (err, notice) => console.log(err || notice.id),
});
```

### Notice properties

The following notice properties are available in `notice` objects:

* `notice.stack` - The stack trace (read only)
* `notice.backtrace` - The parsed backtrace object
* `notice.name` - The exception class name
* `notice.message` - The error message
* `notice.url` - The current url
* `notice.projectRoot` - The root url
* `notice.environment` - Name of the environment. example: “production”
* `notice.component` - Similar to a rails controller name. example: “users”
* `notice.action` - Similar to a rails action name. example: “create”
* `notice.fingerprint` - A unique fingerprint, used to customize grouping of errors in Honeybadger
* `notice.context` - The context object
* `notice.tags` - A string comma-separated list of tags
* `notice.params` - An object of request parameters
* `notice.session` - An object of request session key/values
* `notice.headers` - An object of request headers
* `notice.cookies` - An object of cookie key/values. May also be sent as a string in the document.cookie “foo=bar;bar=baz” format.

The following additional notice properties are available in `afterNotify` handlers:

* `notice.id` - The UUID of the error in Honeybadger

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)