Sourcemaps

Bundled JavaScript throws errors in code nobody wrote. The stack trace points at line 1 of app-4f2b91.js, which tells you nothing. Upload your sourcemaps and Flare turns those frames back into your own files and line numbers.

How it works

1. Your build produces JavaScript files and a sourcemap for each one. Upload the maps to Flare with a version_id you pick.
2. Configure your client to send that same value as sourcemapVersionId on every error report.
3. When a report comes in with a sourcemapVersionId, Flare looks up the maps for that version and resolves each stack frame back to your source.

The version_id is what ties a deployed bundle to its maps, so it has to survive from build time into the running app. A git commit hash works well. Your package version works too, as long as you bump it every release. Never generate it randomly at upload time: the value baked into the bundle would no longer match the value on the maps, and every frame would silently stay minified.

Endpoint

POST https://flareapp.io/api/sourcemaps

Headers

Authentication

This endpoint does not use the x-api-token header. It reads the key field out of the request body instead.

Use your project's public API key, the same one a browser client sends telemetry with. It is safe in build scripts and in your continuous integration pipeline, because it can only upload sourcemaps and send telemetry. See Sending data.

Payload

Example

{
    "key": "your-project-public-api-key",
    "version_id": "9f2c14b",
    "relative_filename": "/build/assets/app-4f2b91.js",
    "sourcemap": "base64-encoded-deflated-sourcemap-content"
}

Encoding

Compress the sourcemap with raw deflate, then base64 encode the result. Raw deflate means no zlib header and no gzip wrapper, which is worth checking twice because most compression helpers add one by default.

In Node:

import { deflateRawSync } from 'node:zlib';

payload.sourcemap = deflateRawSync(sourcemapJson).toString('base64');

In PHP, use gzdeflate() rather than gzencode() or gzcompress():

$payload['sourcemap'] = base64_encode(gzdeflate($sourcemapJson));

Responses

You get a 422 when:

• The base64 or deflate decoding fails
• The decompressed content is empty or is not valid JSON
• The sourcemap is missing version, sources, names or mappings
• The sourcemap version is not 3

One request per file

A build usually produces several JavaScript files, each with its own map. Send one request per file and reuse the same version_id across all of them.

Flare groups maps by version_id and then matches individual stack frames using relative_filename, so the filename has to match what the browser actually requested.

Linking errors to sourcemaps

Send sourcemapVersionId on the error report with the same value you uploaded:

{
    "sourcemapVersionId": "9f2c14b",
    "exceptionClass": "TypeError",
    "stacktrace": [
        {
            "file": "https://acme.test/build/assets/app-4f2b91.js",
            "lineNumber": 1,
            "columnNumber": 28471
        }
    ]
}

Flare resolves each frame's file, lineNumber and columnNumber against the maps for that version.

Send columnNumber. A minified bundle puts an entire module on one line, so the line number on its own cannot identify a position.