Sourcemap not working with esbuild

[gsabran]

Environment

@sentry/esbuild-plugin@^4.3.0
node --version
v22.13.1
macOS 15.5 (24F74)

Steps to Reproduce

I've been following the documentation to upload sourcemaps. However the logs don't show code mapping:

tsconfig.json

{
	"compilerOptions": {
		"target": "esnext",
		"module": "esnext",
		"moduleResolution": "bundler",
		"declaration": true,
		"strict": true,
		"noImplicitAny": false /* Raise error on expressions and declarations with an implied 'any' type. */,
		"strictNullChecks": true,
		"strictFunctionTypes": true /* Enable strict checking of function types. */,
		"noUnusedLocals": false /* Report errors on unused locals. */,
		"noUnusedParameters": false /* Report errors on unused parameters. */,
		"noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
		"noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */,
		"importHelpers": true,
		"skipLibCheck": true,
		"esModuleInterop": true,
		"allowSyntheticDefaultImports": true,
		"experimentalDecorators": true,
		"sourceMap": true,
		"inlineSources": true,
		"outDir": "./dist/tsc/",
		"types": ["node", "jest"],
		"lib": ["ES2024", "DOM"],
		"baseUrl": ".",
		"paths": {
			"@/*": ["src/*"]
		},
		"incremental": true,
		"tsBuildInfoFile": "./dist/tsc/.tsbuildinfo"
	},
	"include": ["src/**/*.ts", "tools/**/*.ts"],
	"exclude": ["node_modules", "dist", "coverage", "**/__snapshots__/**"]
}

build.js

import * as esbuild from "esbuild"
import esbuildPluginTsc from "esbuild-plugin-tsc"
import fs from "fs/promises"
import { sentryEsbuildPlugin } from "@sentry/esbuild-plugin"

const buildOptions = {
	entryPoints: ["src/main.ts"],
	outfile: "dist/main.bundle.cjs",
	bundle: true,
	plugins: [
		esbuildPluginTsc({
			tsconfigPath: "./tsconfig.json",
			force: true,
		}),
	],
	sourcemap: true,
	platform: "node",
	minify: true,
}

if (process.env.NODE_ENV === "production") {
	buildOptions.define = { "process.env.NODE_ENV": '"production"' }

	if (process.env.SENTRY_AUTH_TOKEN === undefined) {
		throw new Error("SENTRY_AUTH_TOKEN is not defined and required for production build")
	}
	buildOptions.plugins.push(sentryEsbuildPlugin({
		authToken: process.env.SENTRY_AUTH_TOKEN,
		org: "<org>",
		project: "<project>",
		telemetry: false,
		debug: true,
	}))
} else {
	buildOptions.define = { "process.env.NODE_ENV": '"development"' }
}

const plugins = [
	{
		name: "post-build-plugin",
		setup(build) {
			build.onEnd(async (result) => {
				if (process.env.NODE_ENV === "production") {
					// Remove the sourcemap, as it has been uploaded to Sentry.
					await fs.unlink("./dist/main.bundle.cjs.map")
				}
			})
		},
	},
]

export const ctx = await esbuild.context({ ...buildOptions, plugins: [...buildOptions.plugins, ...plugins] })

// Check if --watch flag is present in process arguments
if (process.argv.includes("--watch")) {
	// Set up watch mode with hash computation after each rebuild
	ctx.watch()
} else {
	ctx.rebuild()
	ctx.dispose()
}

$ SENTRY_AUTH_TOKEN=... NODE_ENV=production node ./build.js

[sentry-esbuild-plugin] Debug: No `sourcemaps.assets` option provided, falling back to uploading detected build artifacts.
[sentry-esbuild-plugin] Debug: Source map found for bundle `/Users/guigui/dev/cmd/local-server/dist/main.bundle.cjs`: `/Users/guigui/dev/cmd/local-server/dist/main.bundle.cjs.map`
> Found 2 files
> Analyzing 2 sources
> Analyzing completed in 0.017s
> Adding source map references
> Bundling completed in 0.25s
> Bundled 2 files for upload
> Bundle ID: ea74d12d-165f-5e6c-b906-b938c330d101
> Optimizing completed in 0.005s
> Uploading completed in 1.82s
> Uploaded files to Sentry
> Processing completed in 0.184s
> File upload complete (processing pending on server)
> Organization: <Organization>
> Projects: <Projects>
> Release: 96113a8a19990d0a6531580aa5d12ff87377221b
> Dist: None
> Upload type: artifact bundle

Source Map Upload Report
  Scripts
    ~/3e7bec8d-7bf5-456e-b486-cc12baa40a89-0.js (sourcemap at 3e7bec8d-7bf5-456e-b486-cc12baa40a89-0.js.map, debug id 3e7bec8d-7bf5-456e-b486-cc12baa40a89)
  Source Maps
    ~/3e7bec8d-7bf5-456e-b486-cc12baa40a89-0.js.map (debug id 3e7bec8d-7bf5-456e-b486-cc12baa40a89)
[sentry-esbuild-plugin] Info: Successfully uploaded source maps to Sentry
build completed in 6156ms (429bb814da4aa05a555f575ce5bdfe54302aa790ea99553a71086464d6fca3b0)

The debug id seems correctly inserted in the bundle. I assume that the uploaded artifacts have also been modified to contain it:

$ cat ./dist/main.bundle.cjs | grep -oE ".{0,10}3e7bec8d-7bf5-456e-b486-cc12baa40a89.{0,10}"
ugIds[e]="3e7bec8d-7bf5-456e-b486-cc12baa40a89",t._sentr
ntry-dbid-3e7bec8d-7bf5-456e-b486-cc12baa40a89")})()}cat

I then run node ./dist/main.bundle.cjs and trigger an error. The error is reported to Sentry, but the trace is not mapped back to the original code.

If useful, this is in an open source repo, in this branch: https://github.com/getcmd-dev/cmd/tree/gui--node-sentry/local-server

Expected Result

See the error in Sentry with a trace that maps to the original typescript code.

Actual Result

See screenshot. The error trace points to lines in the minified js bundle.

[linear]

BUNDLER-83 Sourcemap not working with esbuild

[Lms24]

Hey @gsabran are you using Sentry SaaS (free tier is enough)? If so, can you post a link to the sentry issue so that I can inspect it? Thanks!

[Lms24]

So I cloned your repo and tried inspecting the local-server/main.bundle.cjs(.map) files. It seems like the generated source maps are somehow invalid because source map visualization tools like this one or this one, cannot read the source map. Something seems to be off with the VLQ encoding. This would explain why Sentry can't symbolicate your errors. I'm not entirely sure what's causing this but I can only recommend to start with systematically reducing build config, used libraries or files.

you can also use this VSCode plugin to visualize the source map. Right now, it doesn't display anything for me (because the source map is invalid)

[gsabran]

Thanks a lot for looking into the repo. I'll check with the tools you provided. It definitively works when I use node --enable-source-maps ./dist/main.bundle.cjs. I'll try to narrow down the issue.

[gsabran]

This is the Sentry issue: https://getcmd.sentry.io/issues/6858843097/?project=4509964777160704&referrer=project-issue-stream

I might have fixed an issue with the handling of node_modules that was making my source map fail validation in the tool you shared:

I'm now stripping source maps from node_modules.

This is a bit unfortunate, as node was able to handle the existing configuration well and would should more detailed traces:

before (node_modules included)	after (node_modules stripped from source map)

With only this modification, my source maps are now validated if I don't include the Sentry plugin, but they are not if I do.

I have to add release: { inject: false } to the sentryEsbuildPlugin for the sourcemap to be validated. With this second change I can see tracing for my code (The vendor code is not mapped)

Here are the different source maps and bundles I got:

bundles.zip

I'm not sure what to make of it, but using the default value for release leads to a much smaller source map:

I updated my branch to #29f8f2 if that helps.