Source maps for error tracking without shipping your source
· SyncYak team
A production error arrives with a stack trace like at e (app.4f2a9c.js:1:48213). It tells you nothing. You need the original file and line, and that is what a source map provides. The catch: a source map is a near-complete copy of your front-end source, so how you handle it matters.
This post covers the safe pattern: generate source maps, upload them to your error tracker, and make sure they never reach your public server.
Why a public source map is a problem
A source map links minified code back to your original files, usually including the original source text. If the .map file is served next to your bundle, anyone can download it and read your front-end code, comments included.
Vercel's documentation on its Next.js conformance rule says this plainly: enabling production source maps publicly shares your application's source code, and disabling them means production errors lack helpful stack traces. Its recommended way out is the one this post follows: upload the maps to your error tracking service, then empty or delete them before deploying to production.
So the choice is not "readable traces or private code". You can have both.
The pattern: build, upload, strip
The flow has three steps, all in CI:
- Build with source maps on. Your bundler writes
.mapfiles next to the bundles. - Upload the maps to your error tracker, tagged with the version of the code they belong to.
- Remove the maps from the deploy output, then deploy.
Two details decide whether this works.
Match the version. The tracker can only apply a map to an error if it knows which build the error came from. Report a code_version (a commit hash works well) from the browser, and upload the maps with the same value. If the two differ by one character, you get minified traces again.
Keep the bundle from advertising the map. Many bundlers append a //# sourceMappingURL= comment to each bundle. If you delete the maps but leave the comment, browsers with dev tools open request a file that returns a 404. It is harmless, but noisy in your logs. Some bundlers can generate maps without that comment; Vite, for example, has a hidden source map mode for this purpose.
A CI sequence you can copy
This sketch uses a generic build script. Replace the commands with your own.
npm run build
export CODE_VERSION="$(git rev-parse HEAD)"
npm run upload-sourcemaps
find dist -name '*.map' -delete
test -z "$(find dist -name '*.map')" || { echo "source maps in output"; exit 1; }
In order, the script builds with maps on, sets the version to the commit hash, uploads the maps for that version (the upload-sourcemaps script is whatever your tracker's plugin or API needs, and its version must match code_version in the browser), deletes every .map file from the output, and fails the build if any remain. Deploy the dist directory only after it passes.
The last check is the one people skip. It turns "we meant to remove the maps" into a check that fails loudly if someone changes the build config later.
Report the version from the browser
On the client, include the same version with every error:
import Rollbar from 'rollbar';
const rollbar = new Rollbar({
accessToken: '<client token>',
endpoint: 'https://api.syncyak.com/api/1/item/',
captureUncaught: true,
captureUnhandledRejections: true,
payload: {
environment: 'production',
client: { javascript: { code_version: __CODE_VERSION__ } },
},
});
__CODE_VERSION__ is a build-time constant your bundler replaces with the commit hash. Use the client token in the browser and a server token in Node.js; both can report to the same project.
Common mistakes
- Uploading maps after the deploy. Errors that arrive in the gap have no map to resolve against. Upload first, deploy second.
- Overwriting a version. Maps are matched by version, so two builds that share a label are ambiguous. Use a unique label per build.
- Forgetting Node.js. Server-side bundles have maps too. They are not served to browsers, but they still belong in the tracker if you bundle your server code.
- Cleaning up too early. Keep maps for as long as you keep errors from that release, or old occurrences turn back into minified traces.
Check that it worked
After the first deploy, trigger a test error from a staging page and open it in your error tracker. You are looking for three things:
- The top stack frame shows your original file name and line, not
app.4f2a9c.js. - Opening
https://your-site.example/assets/app.4f2a9c.js.mapreturns a 404. - A deliberate error from the previous release still resolves, because that release's maps are stored under its own version.
If the first check fails, the usual causes are a version mismatch or maps uploaded after the error was reported. If the second check fails, your deploy step is copying the wrong directory.
How SyncYak helps
SyncYak Cloud Logging accepts the Rollbar SDKs, so for rollbar.js you change the endpoint and keep your error handling. Source maps are matched to the code version you report, and you can upload them from your build with rollbar-sourcemap-webpack-plugin pointed at SyncYak's source map endpoint. They do not need to be served to browsers. Errors are grouped, so a bug that hits thousands of users shows up as one item with a count, and new errors and spikes can post to Slack.
The Free plan collects 10,000 events a month with 14-day retention and no card. Paid plans start at $9 a month for 100,000 events; see pricing for the full ladder. For the JavaScript setup in detail, read JavaScript error tracking with source maps, and for plan limits and project tokens see the Cloud Logging help.
Next step
Add the strip-and-verify steps to your CI pipeline today, even before you pick a tracker: a build that fails when .map files are in the output costs nothing. When you are ready for readable traces, create a free account and send your first test error from staging.