Source maps

Upload .map files with @humanbehavior/wizard so minified production stacks become readable in Issues.

Why

Production bundles are minified. Source maps restore original file names and lines so Issues titles/culprits and fingerprints can key on stable application frames (symbolication runs before fingerprinting on ingest).

Match runtime tags

The SDK stamps these on every error report:

Init option	Env commonly used	Required for maps?
`release`	`HB_RELEASE` / app version	Yes — upload must use the same string
`dist`	`HB_DIST`	Optional discriminator (e.g. `web`, build id)
`commitSha`	`HB_COMMIT_SHA`	Optional; defaults to `git rev-parse HEAD` during upload

HumanBehaviorTracker.init(apiKey, {
  release: process.env.NEXT_PUBLIC_APP_VERSION, // e.g. "1.4.2"
  dist: "web",
  commitSha: process.env.NEXT_PUBLIC_GIT_SHA,
});

If release/dist at runtime disagree with the upload, symbolication will not find maps.

Upload CLI

npx @humanbehavior/wizard upload-sourcemaps [dir] [options]

[dir] defaults to the current directory. The command recursively finds every *.map file and POSTs each to:

POST {ingestionUrl}/api/ingestion/sourcemaps
Authorization: Bearer <apiKey>
Content-Type: application/json

Flags and environment variables

Flag	Env var	Required	Meaning
`--api-key`	`HB_API_KEY`	Yes	Project API key
`--release`	`HB_RELEASE`	Yes	Same release string as SDK init
`--dist`	`HB_DIST`	No	Build discriminator
`--commit`	`HB_COMMIT_SHA`	No	Commit SHA (else `git rev-parse HEAD`)
`--url`	`HB_INGESTION_URL`	No	Ingestion base (default `https://ingest.humanbehavior.co`)
`--help`	—	—	Print usage

Example:

export HB_API_KEY=hb_...
export HB_RELEASE=1.4.2
export HB_DIST=web
npx @humanbehavior/wizard upload-sourcemaps ./dist

Exit codes: non-zero if no .map files are found, or if uploads fail (per-file success/failure is printed).

CI tip

Build with source maps enabled for production artifacts.
Init the SDK with the same release (and dist if used).
Run upload-sourcemaps as a release step against the build output directory.
Do not upload maps for every PR build unless those releases are also what browsers send.

What this does not do

Topic	Status
Automatic webpack/Vite plugin in-repo	Use the wizard CLI (or call the HTTP endpoint yourself)
Public browse of uploaded maps in the UI	Unknown / not documented here — maps are for ingest-time symbolication
Server-side Node stack symbolication	Browser error reports only via this path

Verify

Deploy a minified build with a known release.
Upload maps for that release.
Trigger a production error.
Open the Issue — frames should show original paths/lines after symbolication.

Source maps

On this page