# Honeybadger's esbuild Source Map Plugin

[esbuild](https://esbuild.github.io/) plugin to upload JavaScript
source maps and optionally send deployment notifications to [Honeybadger](https://docs.honeybadger.io/lib/javascript/guides/using-source-maps/).

## 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](https://docs.honeybadger.io/api/reporting-source-maps/) and [Deployments API](https://docs.honeybadger.io/api/reporting-deployments/).

<dl>
  <dt><code>apiKey</code> (required)</dt>
  <dd>The API key of your Honeybadger project</dd>

  <dt><code>assetsUrl</code> (required)</dt>
  <dd>The base URL to production assets (scheme://host/path)<code>*</code><a href="https://docs.honeybadger.io/api/reporting-source-maps/#wildcards">wildcards</a> are supported. The plugin combines <code>assetsUrl</code> with the generated minified js file name to build the API parameter <code>minified_url</code></dd>

  <dt><code>endpoint</code> (optional &mdash; default: "https://api.honeybadger.io/v1/source_maps")</dt>
  <dd>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".</dd>

  <dt><code>revision</code> (optional &mdash; default: "main")</dt>
  <dd>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. <a href="https://docs.honeybadger.io/lib/javascript/guides/using-source-maps.html#versioning-your-project">See the Honeybadger docs for examples</a>.</dd>

  <dt><code>silent</code> (optional &mdash; default: false)</dt>
  <dd>If true, silence logging emitted by the plugin.</dd>

  <dt><code>retries</code> (optional &mdash; default: 3, max: 10)</dt>
  <dd>This package implements fetch retry functionality via the <a href="https://github.com/vercel/fetch-retry">fetch-retry</a> package. Retrying helps fix issues like `ECONNRESET` and `SOCKETTIMEOUT` errors.
  </dd>

  <dt><code>workerCount</code> (optional &mdash; default: 5, min: 1)</dt>
  <dd>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.</br>
  Limited parallelism helps with connection issues in Docker environments.</dd>

  <dt><code>ignorePaths</code> (optional &mdash; default: [])</dt>
  <dd>An array of paths (glob patterns) to ignore when uploading source maps. Uses <a href="https://github.com/micromatch/picomatch">picomatch</a> to match against paths. 
  </dd>

  <dt><code>deployEndpoint</code> (optional &mdash; default: "https://api.honeybadger.io/v1/deploys")</dt>
  <dd>Where to send deployment notifications. If you are using our EU stack, you should set this to "https://eu-api.honeybadger.io/v1/deploys".</dd>

  <dt><code>deploy</code> (optional &mdash; default: false)</dt>
  <dd>
  Configuration for <a href="https://docs.honeybadger.io/api/reporting-deployments/">deployment notifications</a>. To disable deployment notifications, ignore this option. To enable deployment notifications, set this to <code>true</code>, or to an object containing any of the fields below. Your deploy's <code>revision</code> will be set to the same value as for your source maps (see above). 

  <dl>
    <dt><code>environment</code></dt>
    <dd>The environment name, for example, "production"</dd>
    <dt><code>repository</code></dt>
    <dd>The base URL of the VCS repository (HTTPS-style), for example, "https://github.com/yourusername/yourrepo"</dd>
    <dt><code>localUsername</code></dt>
    <dd>The name of the user that triggered this deploy, for example, "Jane"</dd>
  </dl>
  </dd>

  <dt><code>developmentEnvironments</code> (optional &mdash; default: ["dev", "development", "test"])</dt>
  <dd>Used to decide whether source maps should be uploaded or not.</dd>
</dl>

### esbuild.config.js
Set `sourcemap` to `true`. Add the honeybadger plugin to the plugins array.
```javascript
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](./MIT-LICENSE) file in this folder for details.