Source maps
The code that reaches the browser is usually minified, so its stack trace points at /assets/index-a1b2c3d4.js:1:48213 in e. If you upload each build's source maps, Collector shows src/cart/coupon.ts:5 in applyCoupon, with the lines around it, and groups errors by your original code: a new build doesn't open new issues. The same goes for a bundled Node server.
What you need
- An upload token (
cltu_…), kept in your CI's secrets asCOLLECTOR_UPLOAD_TOKEN. - The project's DSN in
COLLECTOR_DSN, to know where Collector is. - The
collectorCLI in your CI. - The same release in the upload and in your application: the
releasethe SDK sends.
Uploading
Before you deploy: events from a release whose maps aren't uploaded yet stay minified.
collector upload ./dist --release "$GIT_SHA"
The CLI finds every .map file under the directory and pairs it with its bundle (by the sourceMappingURL comment, the map's file field, or the name). It only uploads the maps, not the minified code. It warns about maps without sourcesContent (without it there are no lines of code to show) and skips those over 20 MB.
| Option | Default | |
|---|---|---|
--release | COLLECTOR_RELEASE | Required. The release your application reports. |
--dsn | COLLECTOR_DSN | The project's DSN. |
--url-prefix | / | The URL path the directory is served at, like /static/. |
--delete | off | Deletes the .map files (and the comments pointing at them) after uploading. |
--dry-run | off | Lists what it would upload, sending nothing. |
Instead of an upload token and the DSN, an access token of an owner or admin of the project also works, with --org and --project. If there's an upload token, it always wins.
Uploading the same release and path again replaces that map, so retrying is safe.
With Vite
Set the release at build time and keep the maps out of the bundle; then upload and delete them:
// vite.config.ts
export default defineConfig({
define: { __COLLECTOR_RELEASE__: JSON.stringify(process.env.GIT_SHA) },
build: { sourcemap: "hidden" },
});
vite build && collector upload ./dist --release "$GIT_SHA" --delete
The browser SDK reads __COLLECTOR_RELEASE__ if you don't pass release to init. With webpack: new DefinePlugin({ __COLLECTOR_RELEASE__: JSON.stringify(sha) }).
With Next.js
Next.js's server code is bundled too:
collector upload .next/server --url-prefix /.next/server --release "$GIT_SHA"
See Node.
How they're applied
When an event arrives, each frame with a line and column is looked up by the event's release and the file's path. Only the path counts: a full URL's origin, query and fragment are dropped, so https://cdn.example.com/assets/app.js?v=2 matches /assets/app.js. The same maps serve every environment of a release.
A resolved frame shows the original file, line and column, with its code, and counts as yours unless it's under node_modules or deps.
Maps aren't applied to events that arrived before them, but Collector regroups those events by the original code, and if that makes two issues match, it merges them. An issue's page says when its release's maps are missing.
The upload format details are in the protocol.