Skip to content
Bugtail Docs
Start free
Menu

Source maps

Browsers run minified JavaScript, so a stack trace from production points at line 1, column 48213 of app.4f2a91.js. Upload the source maps of each release and Bugtail shows the file, line and function you wrote instead.

What you need

  • A collector that receives your browser events, and its upload secret. Issue one on the collector under Settings > Projects and collectors. It is shown once, so store it with your other build secrets.
  • The same release in your SDK as in your upload. See Releases.
  • Source maps from your build. Most bundlers write them next to the bundle when you turn them on, for example build.sourcemap: true in Vite.

Upload

Upload each .map file after the build, before or right after you deploy:

curl -X POST https://ingest.bugtail.eu/api/<project-id>/artifacts/ \
  -H "Authorization: Bearer <key>" \
  -H "X-Bugtail-Secret: $BUGTAIL_SECRET" \
  -F release=1.4.0 \
  -F name='~/assets/app.js.map' \
  -F file=@dist/assets/app.js.map

To upload every map of a build at once:

for map in dist/assets/*.js.map; do
  curl -X POST https://ingest.bugtail.eu/api/<project-id>/artifacts/ \
    -H "Authorization: Bearer <key>" \
    -H "X-Bugtail-Secret: $BUGTAIL_SECRET" \
    -F release="$RELEASE" \
    -F name="~/assets/$(basename "$map")" \
    -F file=@"$map"
done

The collector screen shows the command with your project id and key filled in. The response says what was stored, so a failed upload shows up in your build log.

How maps are matched

  • By release: a map is only used for events of the release it was uploaded for.
  • By file name: a frame in https://example.com/assets/app.4f2a91.js uses the map named app.4f2a91.js.map. The ~ in name stands for any host, and a full URL works too.

Give every bundle a unique file name within a release. Bundlers do this already when they add a content hash.

Uploading a map with the same name again replaces it. Maps are applied when you open an event, so a map uploaded after the error happened still works for it.

Original source code

When a map includes the original sources, which most bundlers do by default, the issue page also shows the lines of code around each frame.

Keep maps off your public site

Bugtail does not need your maps to be downloadable. You can upload them and then delete them from the build output, so visitors cannot read your original source.