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 pluginCopy Anchor Link

Install the package in the app that builds your frontend.

Copy Text
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.

Copy Text
FASTSTATS_SOURCEMAP_KEY=your_sourcemap_upload_key

Add it to your bundlerCopy Anchor Link

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.

Copy Text
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,
		}),
	],
});

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

Recommended production setupCopy Anchor Link

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

Copy Text
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.

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

Build IDsCopy Anchor Link

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.

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

OptionsCopy Anchor Link

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 uploadsCopy Anchor Link

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

Copy Text
{
	"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.

Copy Text
Authorization: Bearer <FASTSTATS_SOURCEMAP_KEY>