Sourcemaps

FastStats can turn minified browser stack traces back into the original file, line and column when you upload the sourcemaps from the same build.

The easiest way to do this is with @faststats/sourcemap-uploader-plugin. The plugin runs during your production build, uploads every .map file it finds and adds the build ID to your JavaScript bundle. The FastStats web SDK reads that build ID when it reports an error, so FastStats can choose the matching sourcemap.

Install the plugin

Install the package in the app that builds your frontend.

npm install --save-dev @faststats/sourcemap-uploader-plugin

You also need a sourcemap upload key from your FastStats project settings. Store it as a secret in CI and pass it to the plugin with authToken.

FASTSTATS_SOURCEMAP_KEY=your_sourcemap_upload_key

Add it to your bundler

Turn on sourcemap output in your bundler, then add the FastStats plugin. The default upload endpoint is https://sourcemaps.faststats.dev/v0/upload, so most projects only need to pass authToken.

import { defineConfig } from "vite";
import sourcemapsPlugin from "@faststats/sourcemap-uploader-plugin/vite";

export default defineConfig({
	build: {
		sourcemap: true,
	},
	plugins: [
		sourcemapsPlugin({
			authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
		}),
	],
});

import sourcemapsPlugin from "@faststats/sourcemap-uploader-plugin/rollup";

export default {
	input: "src/index.ts",
	output: {
		dir: "dist",
		format: "es",
		sourcemap: true,
	},
	plugins: [
		sourcemapsPlugin({
			authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
		}),
	],
};

import sourcemapsPlugin from "@faststats/sourcemap-uploader-plugin/webpack";

export default {
	devtool: "source-map",
	plugins: [
		sourcemapsPlugin({
			authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
		}),
	],
};

import sourcemapsPlugin from "@faststats/sourcemap-uploader-plugin/rspack";

export default {
	devtool: "source-map",
	plugins: [
		sourcemapsPlugin({
			authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
		}),
	],
};

import { build } from "esbuild";
import sourcemapsPlugin from "@faststats/sourcemap-uploader-plugin/esbuild";

await build({
	entryPoints: ["src/index.ts"],
	bundle: true,
	sourcemap: true,
	outfile: "dist/app.js",
	plugins: [
		sourcemapsPlugin({
			authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
		}),
	],
});

The package also exports rolldown, farm, bun and unloader adapters. Use the adapter that matches your bundler and keep sourcemap output enabled.

Recommended production setup

Run the upload as part of the same CI job that builds and deploys your frontend. Keep the upload key in your CI secrets.

name: Build

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci
      - run: npm run build
        env:
          FASTSTATS_SOURCEMAP_KEY: ${{ secrets.FASTSTATS_SOURCEMAP_KEY }}

If your public site does not need to serve sourcemaps, set deleteAfterUpload: true. The plugin deletes local .map files only after a successful upload.

sourcemapsPlugin({
	authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
	deleteAfterUpload: true,
});

Build IDs

Every upload has a buildId. The browser error reporter sends the same build ID with each error, which is how FastStats finds the right sourcemap.

By default the plugin uses the current git commit hash. If git is not available, it creates a random ID for that build. You can also set the ID yourself.

sourcemapsPlugin({
	authToken: process.env.FASTSTATS_SOURCEMAP_KEY,
	buildId: process.env.GITHUB_SHA,
});

Options

authToken is the bearer token used to upload sourcemaps. You should almost always set it from an environment variable.

endpoint changes where sourcemaps are uploaded. Use this only if you are using a self hosted sourcemap service.

buildId sets the build ID manually. If you leave it empty, the plugin uses the current git commit hash when it can.

deleteAfterUpload removes .map files after a successful upload.

failOnError controls whether a failed upload fails the build. It is true by default.

enabled can turn the plugin on or off. It accepts a boolean or a function that receives the bundler name.

maxUploadBodyBytes controls the largest upload request body. The default is 50 MB. Larger sourcemap sets are split into multiple upload requests.

globalKey changes the runtime global used for build metadata. The default is __SOURCEMAPS_BUILD__.

onUploadSuccess and onUploadError let you run custom code after an upload succeeds or fails.

What the plugin uploads

The plugin sends JSON to /v0/upload with the mapping type, build ID, upload time and sourcemap files.

{
	"type": "javascript",
	"buildId": "build-123",
	"uploadedAt": "2026-04-01T12:00:00.000Z",
	"files": [
		{
			"fileName": "assets/app.js.map",
			"content": "{...}"
		}
	]
}

The request uses bearer auth with your sourcemap upload key.

Authorization: Bearer <FASTSTATS_SOURCEMAP_KEY>