honeybadger-js

Honeybadger for JavaScript

Welcome! This monorepo contains all Honeybadger packages for JavaScript. Refer to each package's README for more information and setup instructions:

@honeybadger-io/core

The core package that integrates with the Honeybadger API
@honeybadger-io/js

SDK for browsers, Node.js, and AWS Lambda
@honeybadger-io/webpack

Webpack plugin for uploading source maps to Honeybadger
@honeybadger-io/vue

SDK for Vue.js integration
@honeybadger-io/react

SDK for React integration
@honeybadger-io/nextjs

SDK for Next.js integration
@honeybadger-io/gatsby-plugin-honeybadger

Gatsby plugin
@honeybadger-io/react-native

SDK for React Native integration
@honeybadger-io/rollup-plugin

Rollup/Vite plugin for uploading source maps to Honeybadger
@honeybadger-io/esbuild-plugin

esbuild plugin for uploading source maps to Honeybadger
@honeybadger-io/plugin-core

Utility functions shared by the Rollup, Webpack, and esbuild plugins
@honeybadger-io/cloudflare

Error monitoring integration for Cloudflare Workers

Documentation and Support

For comprehensive documentation and support, see our docs: https://docs.honeybadger.io/lib/javascript/index.html

Changelog

Each package's CHANGELOG.md is updated when a new version is released (pnpm run release).
Conventional Commits are enforced with a Git hook (via husky + commitlint) in order to automate changelog generation.

Contributing

Fork the repo.
Create a topic branch git checkout -b my_branch
Commit your changes git commit -am "chore: boom"
Push to your branch git push origin my_branch
Send a pull request

Development

We use pnpm workspaces and Lerna to manage the monorepo. Lerna helps us:

generate changelogs and bump versions (based on conventional commits) and
publish to NPM

pnpm owns install/linking (including the workspace: protocol for in-repo deps).

Enable Corepack (ships with Node) so the pinned pnpm version from packageManager is used: corepack enable
Run pnpm install from the monorepo root.
Run pnpm test from the monorepo root to run unit tests for all packages.

Lerna / pnpm Tips

Always install from the root, i.e. pnpm install only from the root folder, otherwise you may get unexpected issues with the linked packages.
Use pnpm add my-pkg --filter @honeybadger-io/js to add my-pkg to the @honeybadger-io/js project. Or you can manually add to the target project's package.json file (use workspace:^ for in-repo deps). You still need to run pnpm install from the root.
Use lerna run or pnpm --filter to execute commands for projects. If the command is not found it will not be executed. You can filter the packages using --scope / --filter. For example, lerna run test will execute test in all packages that have this script available.

[!TIP] For more info, you can read the Lerna docs and pnpm workspace docs.

Troubleshooting TypeScript

Not seeing changes when working in .ts files? Make sure that you rebuild every time you make a change. Or enable "compile on save" with your IDE — WebStorm (JetBrains) / VS Code.
If you are getting errors with TypeScript, make sure that you run pnpm run build. It's a prerequisite for TypeScript Project References.

Releasing

Packages in the monorepo are released in independent mode, meaning that Lerna will decide which packages to release and what version bump to apply based on the commits since the last release.

Releases are performed via GitHub Actions, which run pnpm run release. That command calls lerna publish, which:

generates the changelog based on commit messages (see Changelog above)
bumps package versions
publishes to NPM

[!NOTE] Some packages may have a postpublish script, for example @honeybadger-io/js (found in packages/js) has a script to also publish to our js.honeybadger.io CDN (hosted on AWS via S3/CloudFront).

Release Automation

The repository automatically releases new packages when a PR is merged on master using the Publish Release workflow (lerna-publish.yml).

The same workflow can also be run manually (Run workflow) with a mode input, for when a release only partially succeeds:

Mode	What it does
`full` (default)	Runs CI, then `pnpm run release`: bumps versions, generates changelogs, publishes to NPM, uploads to the CDN and creates the GitHub release. This is what a push to `master` runs.
`npm`	Re-publishes the versions already committed to `master` (`lerna publish from-package`), skipping CI. Use when versioning and the GitHub release succeeded but NPM publishing failed. The `@honeybadger-io/js` `postpublish` script runs as part of it, so the CDN is updated too.
`cdn`	Re-uploads the `packages/js` browser bundle to the CDN only, skipping CI. Use when NPM publishing succeeded but the CDN upload failed.

[!NOTE] All three modes live in a single workflow file on purpose. NPM Trusted Publishing binds to a workflow filename and is configured per package, so running a fallback from a separate workflow file would mean switching the Trusted Publisher on every package and switching it back afterwards. With one file, the fallback modes need no NPM-side changes.

[!WARNING] Only users with write permissions can trigger this workflow (i.e. Collaborators).

Available Commands

pnpm run release - Calculates the next version, commits and publishes to NPM (and to our CDN). This command is executed from the Publish Release workflow.

Releasing Package For The First Time

If you are publishing a new package on NPM, the Publish Release workflow (lerna-publish.yml) will fail with a 404 error message. This is because the workflow assumes Trusted Publishing has been set up for all packages, but since this is a new package, there's no way for Trusted Publishing to have been set up. Therefore, a manual release is required:

Allow the automated release workflow to fail. NPM publishing will fail, but changelog generation and GitHub release will be successful.
Then, check out the master branch locally and pull the latest changes.
npm login
lerna publish from-package --yes --loglevel silly

[!NOTE] A manual release can also be used any time NPM Trusted Publishing does not work.

[!IMPORTANT] If the @honeybadger-io/js package is among those being released, its postpublish script (packages/js/scripts/release-cdn.sh) runs as part of the publish. That script relies on secret variables that are normally injected by CI, so you must export them in your shell before running the publish command:
export HONEYBADGER_JS_S3_BUCKET=honeybadger-js
export HONEYBADGER_DISTRIBUTION_ID=cloudfront-id
export BUNNY_API_KEY=bunny-api-key
export AWS_ACCESS_KEY_ID=aws-access-key-id
export AWS_SECRET_ACCESS_KEY=aws-secret-access-key

License

This Honeybadger repository and published packages are MIT licensed. See the MIT-LICENSE file in this repository for details.

README