JavaScript needs Debug IDs
A couple months ago Sentry created a brand new NPM organization (namespace) for debug ids and published a set of packages under that namespace: https://www.npmjs.com/org/debugids
This represents a big step to getting JavaScript debug ids more formally recognized across the JavaScript ecosystem. It also shows how Sentry is developing the maturity to lead open standards and engage in consensus building.
💡 TL;DR
- Debug IDs are deterministic, globally unique values that connect a JavaScript file to their source map.
- Sentry is now attempting to make JavaScript debug ids not just a Sentry-specific concept - but one that exists across the entire JavaScript ecosystem.
- We’re pushing forward an official tc39 proposal to add debug ids to the source map spec alongside browser APIs to interact with debug ids.
- We’ve published a set of plugins, tools, and polyfills that anyone can use to add debug id support to their tooling/applications and we are collaborating with the JavaScript community to add debug id support to bundlers and source maps tooling
Want to learn more? Read on!
Developers of modern websites often use some kind of build process when they add JavaScript to the site. This build process takes some input JavaScript, transforms it in some way, then outputs JavaScript that is served alongside the website. Some example transformations include minifying JavaScript code (so the final JavaScript bundle is smaller and faster to load) or removing TypeScript types (only JavaScript can run on the browser).
This means that in 99% of cases, the JavaScript that you run is not the JavaScript you wrote in your editor. It’s been transformed, transpiled, downcompiled, polyfilled, and more!
Stack traces are essential to debug errors that Sentry captures, but stack traces that come from generated JavaScript are often unreadable or unusable! They look nothing like the code you wrote, you can’t connect them to your source code repository, and minified variables or function names make you lose context about what is happening.
To make sure that Sentry (or other tools) can make a stack trace readable and useful, you can generate and leverage source maps. Source maps are a file that contains mapping information between a transformed JavaScript file, and its original JavaScript file. Sentry can use source maps to figure out the original source from a transformed JavaScript file, which means you’ll get stack frames that look like the code you wrote, not the code you generated.
To connect source maps to a JavaScript file, we relied on filenames, but these often were unreliable. For example, a new deploy of a source map with the same filename would mean the source mapping gets incorrectly applied.
//# source mappingURL=http://example.com/path/to/your/source map.map
Given the url-based filename approach was unreliable, we came up with debug ids. Inspired by approaches in native language ecosystems, debug ids are globally unique, deterministic ids that identify a transformed JavaScript file and its associated source map.
We’ve found that using debug ids for our source mapping infrastructure has made it easier for users to get source-mapped errors to work, which vastly increases the usefulness of JavaScript stacktraces in Sentry. In addition, the usage of debug ids has decoupled sourcemapping from releases, which reduces the barrier of entry for new users to set up sourcemaps in Sentry.
In the last month alone we’ve had over 25k organizations use upload source maps with debug ids, totalling 7.9 million total uploads.
All in all, debug id usage has been a huge success for us at Sentry and our users.
While we adopted debug ids for our source mapping needs at Sentry, we also sent a proposal in to tc39, the JavaScript standards committee, to add debug id as an official part of the source map spec. This was initially added by Armin back in April of 2023, and then was further amended by Luca (who also attended meetings with the tc39 source map working group to push this forward). We now have a stage 2 tc39 source maps proposal to add debug ids to the official source maps spec.
We’re going to keep pushing this forward in tc39 to proceed through the various stages and implement this.
Aside from tc39, we’d like to see JavaScript tooling and the browsers themselves add support for debug ids. To make this easy to adopt, we published a set of JavaScript libraries under the @debugids namespace. You can see them listed below:
@debugids/browser- A browser polyfill for debug ids functionality
@debugids/node- A node polyfill for debug ids functionality
@debugids/cli- CLI tooling at allows you to add debug ids to transformed files and their corresponding sourcemaps
@debugids/esbuild- Esbuild plugin that adds debug id support
@debugids/parcel-optimizer-debugids- Parcel plugin that adds debug id support
@debugids/rolldown- Rolldown plugin that adds debug id support
@debugids/rollup- Rollup plugin that adds debug id support
@debugids/rspack- Rspack plugin that adds debug id support
@debugids/vite- Vite plugin that adds debug id support
@debugids/webpack- Webpack plugin that adds debug id support
With these packages, we can now start showing others how to adopt debug ids for their purposes. Up-streaming debug id support into the bundlers and JavaScript itself gives us three benefits:
We reduce the maintenance burden of debug id support in our own bundler plugins and sentry-cli tooling.
We reduce the complexity of SDK logic/bundle size hit of the SDK if Debug ID functionality is exposed as JavaScript or browser API.
We establish Sentry as an important part of the web community pushing standards forward, and engaging in consensus building across different organizations and companies (something, something brand?).
We initially aimed to just share these packages with library and tooling authors for them to make changes themselves, but we were surprised by how receptive JavaScript library authors were to accept our PRs to add debug id functionality.
Even before we started our work and published libraries under the @debugid namespace, the Bun Bundler added support for Debug IDs.
Our work started off by approaching Rolldown, a Rust-based bundler that will soon power Vite. In just a couple days after opening the PR to add Debug ID support, they merged it!
In addition to Rolldown, we also PR’d and added debug ids functionality to:
Rollup (pull request)
Webpack (pull request)
Vite (pull request)
Rspack (issue with pull requests)
We also raised the Debug ID support with Esbuild and v8 (Chrome), but these were not followed up on because the proposal is only at Stage 2 at the moment.
Big thanks to Tim Fish for pushing forward the work around bundlers and JavaScript tooling related to Debug IDs.
With support from Rollup, Rolldown, Rspack, Vite, and Webpack, the ecosystem is in a great position to take advantage of debug ids.
Now that all the major bundlers support debug ids, we just have to work toward pushing forward the debug ids proposal in TC39. We’re excited to see that go to Stage 3 and beyond, and become a part of JavaScript permanently.
We’ve gotten so much value out of JavaScript debug ids internally, and we’re excited to how the community can benefit now that it’s more generally available. JavaScript needs debug ids - and now they are there for everyone to use!
