@honeybadger-io/esbuild-plugin

Honeybadger's esbuild Source Map Plugin

esbuild plugin to upload JavaScript source maps and optionally send deployment notifications to Honeybadger.

Installation

# npm
npm install @honeybadger-io/esbuild-plugin --save-dev

# yarn
yarn add @honeybadger-io/esbuild-plugin --dev

Configuration

Plugin parameters

These plugin parameters correspond to the Honeybadger Source Map Upload API and Deployments API.

apiKey (required)

The API key of your Honeybadger project

assetsUrl (required)

The base URL to production assets (scheme://host/path)*wildcards are supported. The plugin combines assetsUrl with the generated minified js file name to build the API parameter minified_url

endpoint (optional — default: "https://api.honeybadger.io/v1/source_maps")

Where to upload your source maps to. Perhaps you have a self hosted source map server you would like to upload your source maps to instead of Honeybadger. If you are using our EU stack, you should set this to "https://eu-api.honeybadger.io/v1/source_maps".

revision (optional — default: "main")

The deploy revision (i.e. commit hash) that your source map applies to. This could also be a code version. For best results, set it to something unique every time your code changes. See the Honeybadger docs for examples.

silent (optional — default: false)

If true, silence logging emitted by the plugin.

retries (optional — default: 3, max: 10)

This package implements fetch retry functionality via the fetch-retry package. Retrying helps fix issues like `ECONNRESET` and `SOCKETTIMEOUT` errors.

workerCount (optional — default: 5, min: 1)

Source maps are uploaded in parallel by a configurable number of workers. Increase or decrease this value to configure how many source maps are being uploaded in parallel.
Limited parallelism helps with connection issues in Docker environments.

ignorePaths (optional — default: [])

An array of paths (glob patterns) to ignore when uploading source maps. Uses picomatch to match against paths.

deployEndpoint (optional — default: "https://api.honeybadger.io/v1/deploys")

Where to send deployment notifications. If you are using our EU stack, you should set this to "https://eu-api.honeybadger.io/v1/deploys".

deploy (optional — default: false)

Configuration for deployment notifications. To disable deployment notifications, ignore this option. To enable deployment notifications, set this to true, or to an object containing any of the fields below. Your deploy's revision will be set to the same value as for your source maps (see above).

environment

The environment name, for example, "production"

repository

The base URL of the VCS repository (HTTPS-style), for example, "https://github.com/yourusername/yourrepo"

localUsername

The name of the user that triggered this deploy, for example, "Jane"

developmentEnvironments (optional — default: ["dev", "development", "test"])

Used to decide whether source maps should be uploaded or not.

esbuild.config.js

Set sourcemap to true. Add the honeybadger plugin to the plugins array.

import { honeybadgerSourceMapPlugin } from '@honeybadger-io/esbuild-plugin'

// See plugin params above
const hbPluginOptions = {
  apiKey: 'your_key_here', 
  assetsUrl: 'https://yoursite.foo', 
  revision: 'v1.0.0',
}

esbuild
    .build({
        entryPoints: ['src/index.ts'],
        bundle: true,
        minify: true,
        format: 'cjs',
        sourcemap: true,
        outfile: 'dist/output.js',
        plugins: [honeybadgerSourceMapPlugin(hbPluginOptions)]
    })
    .then(() => {
        console.log('Build complete')
    })
    .catch((err) => {
        console.error(err)
        process.exit(1)
    });

Development

1. Run npm install
2. Run the tests with npm test
3. Build with npm run build

See the /examples folder for projects to test against.

License

This package is MIT licensed. See the MIT-LICENSE file in this folder for details.