|
| 1 | +# Honeybadger's esbuild Source Map Plugin |
| 2 | + |
| 3 | +[esbuild](https://esbuild.github.io/) plugin to upload JavaScript |
| 4 | +source maps and optionally send deployment notifications to [Honeybadger](https://docs.honeybadger.io/lib/javascript/guides/using-source-maps/). |
| 5 | + |
| 6 | +## Installation |
| 7 | + |
| 8 | +``` |
| 9 | +# npm |
| 10 | +npm install @honeybadger-io/esbuild-plugin --save-dev |
| 11 | +
|
| 12 | +# yarn |
| 13 | +yarn add @honeybadger-io/esbuild-plugin --dev |
| 14 | +``` |
| 15 | + |
| 16 | + |
| 17 | +## Configuration |
| 18 | + |
| 19 | +### Plugin parameters |
| 20 | + |
| 21 | +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/). |
| 22 | + |
| 23 | +<dl> |
| 24 | + <dt><code>apiKey</code> (required)</dt> |
| 25 | + <dd>The API key of your Honeybadger project</dd> |
| 26 | + |
| 27 | + <dt><code>assetsUrl</code> (required)</dt> |
| 28 | + <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> |
| 29 | + |
| 30 | + <dt><code>endpoint</code> (optional — default: "https://api.honeybadger.io/v1/source_maps")</dt> |
| 31 | + <dd>Where to upload your source maps to. Perhaps you have a self hosted |
| 32 | + source map server you would like to upload your source maps to instead |
| 33 | + of Honeybadger.</dd> |
| 34 | + |
| 35 | + <dt><code>revision</code> (optional — default: "main")</dt> |
| 36 | + <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> |
| 37 | + |
| 38 | + <dt><code>silent</code> (optional — default: false)</dt> |
| 39 | + <dd>If true, silence logging emitted by the plugin.</dd> |
| 40 | + |
| 41 | + <dt><code>retries</code> (optional — default: 3, max: 10)</dt> |
| 42 | + <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. |
| 43 | + </dd> |
| 44 | + |
| 45 | + <dt><code>workerCount</code> (optional — default: 5, min: 1)</dt> |
| 46 | + <dd>Source maps are uploaded in parallel by a configurable number of |
| 47 | + workers. Increase or decrease this value to configure how many source maps |
| 48 | + are being uploaded in parallel.</br> |
| 49 | + Limited parallelism helps with connection issues in Docker environments.</dd> |
| 50 | + |
| 51 | + <dt><code>ignorePaths</code> (optional — default: [])</dt> |
| 52 | + <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. |
| 53 | + </dd> |
| 54 | + |
| 55 | + <dt><code>deployEndpoint</code> (optional — default: "https://api.honeybadger.io/v1/deploys")</dt> |
| 56 | + <dd>Where to send deployment notifications.</dd> |
| 57 | + |
| 58 | + <dt><code>deploy</code> (optional — default: false)</dt> |
| 59 | + <dd> |
| 60 | + 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). |
| 61 | + |
| 62 | + <dl> |
| 63 | + <dt><code>environment</code></dt> |
| 64 | + <dd>The environment name, for example, "production"</dd> |
| 65 | + <dt><code>repository</code></dt> |
| 66 | + <dd>The base URL of the VCS repository (HTTPS-style), for example, "https://github.com/yourusername/yourrepo"</dd> |
| 67 | + <dt><code>localUsername</code></dt> |
| 68 | + <dd>The name of the user that triggered this deploy, for example, "Jane"</dd> |
| 69 | + </dl> |
| 70 | + </dd> |
| 71 | +</dl> |
| 72 | + |
| 73 | +### esbuild.config.js |
| 74 | +Set `sourcemap` to `true`. Add the honeybadger plugin to the plugins array. |
| 75 | +```javascript |
| 76 | +import { honeybadgerSourceMapPlugin } from '@honeybadger-io/esbuild-plugin' |
| 77 | + |
| 78 | +// See plugin params above |
| 79 | +const hbPluginOptions = { |
| 80 | + apiKey: 'your_key_here', |
| 81 | + assetsUrl: 'https://yoursite.foo', |
| 82 | + revision: 'v1.0.0', |
| 83 | +} |
| 84 | + |
| 85 | +esbuild |
| 86 | + .build({ |
| 87 | + entryPoints: ['src/index.ts'], |
| 88 | + bundle: true, |
| 89 | + minify: true, |
| 90 | + format: 'cjs', |
| 91 | + sourcemap: true, |
| 92 | + outfile: 'dist/output.js', |
| 93 | + plugins: [honeybadgerSourceMapPlugin(hbPluginOptions)] |
| 94 | + }) |
| 95 | + .then(() => { |
| 96 | + console.log('Build complete') |
| 97 | + }) |
| 98 | + .catch((err) => { |
| 99 | + console.error(err) |
| 100 | + process.exit(1) |
| 101 | + }); |
| 102 | +``` |
| 103 | + |
| 104 | +## Development |
| 105 | + |
| 106 | +1. Run `npm install` |
| 107 | +2. Run the tests with `npm test` |
| 108 | +3. Build with `npm run build` |
| 109 | + |
| 110 | +See the `/examples` folder for projects to test against. |
| 111 | + |
| 112 | +## License |
| 113 | + |
| 114 | +This package is MIT licensed. See the [MIT-LICENSE](./MIT-LICENSE) file in this folder for details. |
0 commit comments