feat: esbuild plugin (#1318)

.github/workflows/node.js.yml

@@ -75,7 +75,7 @@ jobs:
     - name: Setup Node.js
       uses: actions/setup-node@v3
       with:
-        node-version: '14.x'
+        node-version: '18.x'
         cache: 'npm'
         cache-dependency-path: |
           package-lock.json
@@ -115,16 +115,9 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '14.x'
+          node-version: '18.x'
           cache: 'npm'
-          cache-dependency-path: |
-            package-lock.json
-            packages/js/examples/aws-lambda-typescript/package-lock.json
-            packages/vue/examples/vue2/package-lock.json
-            packages/vue/examples/vue3/package-lock.json
-            packages/react-native/example/package-lock.json
-            packages/nextjs/examples/app-router/package-lock.json
-            packages/nextjs/examples/pages-router/package-lock.json
+          cache-dependency-path: package-lock.json
 
       - name: Build
         run: npm ci

.gitignore

@@ -11,4 +11,6 @@ lerna-debug.log
 browserstack.err
 
 # for use with direnv
-.envrc
+.envrc
+
+.rollup.cache

packages/esbuild-plugin/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2024 Honeybadger Industries LLC
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

packages/esbuild-plugin/README.md

@@ -0,0 +1,114 @@
+# 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.</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.</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>
+</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.

packages/esbuild-plugin/examples/.eslintrc.json

@@ -0,0 +1,7 @@
+{
+    "rules": {
+      // Since these are just examples, the monorepo's linting should not
+      // fail just because we didn't run `npm install` in the example folders
+        "import/no-unresolved": ["off"]
+      }
+}

packages/esbuild-plugin/examples/react-ssr/esbuild.config.mjs

@@ -0,0 +1,18 @@
+import * as esbuild from 'esbuild'
+import { honeybadgerSourceMapPlugin } from '../../dist/index.js'
+
+const hbOptions = {
+    apiKey: process.env.HONEYBADGER_API_KEY,
+    assetsUrl: 'https://example.com/public',
+    revision: 'esbuild-plugin-react-ssr-example',
+}
+
+await esbuild.build({
+    entryPoints: ['src/app.jsx'],
+    bundle: true,
+    minify: true,
+    sourcemap: true,
+    target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
+    outfile: 'dist/out.js',
+    plugins: [honeybadgerSourceMapPlugin(hbOptions)]
+})