Sourcemaps Reference

Improve your debugging workflow by mapping compressed production code back to your original source files.
This guide covers how to integrate sourcemaps into your FastStats project.

Overview

FastStats leverages sourcemaps to provide readable stack traces. Instead of seeing errors from minified bundles, you can view the exact line of code in your original source files where an issue occurred.

Upload Methods

FastStats supports multiple ways to provide sourcemaps:

1. Public URL References

Add direct URLs to your publicly accessible .map files in the project settings.

1. Navigate to Project Settings → Sourcemaps
2. In the Source Maps section, enter the public URL to your .map file
3. Click the + button to add it

This method is suitable for sourcemaps hosted on CDNs or public servers.

2. API Upload

Upload sourcemaps directly via the FastStats API. This is the recommended method for private sourcemaps and CI/CD integration.s

Generate an API Key

1. Navigate to Project Settings → Sourcemaps
2. In the Sourcemap Upload API Key section, click Generate API Key
3. Copy and securely store the key - it will only be shown once

Upload via cURL

curl -X POST https://sourcemaps.faststats.dev/v1/sourcemaps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@dist/app.js.map" \
  -F "file=@dist/vendor.js.map"

You can upload multiple sourcemap files in a single request.

3. GitHub Action

Use the official GitHub Action to automatically upload sourcemaps during your CI/CD pipeline.

name: Deploy

on:
  push:
    branches: [main]

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

      - name: Build
        run: npm run build

      - name: Upload Sourcemaps
        uses: faststats-dev/upload-sourcemaps@v0.2
        with:
          dist-dir: dist
          api-key: ${{ secrets.FASTSTATS_SOURCEMAP_KEY }}

Action Inputs

Self-Hosted Instances

If you're running a self-hosted FastStats instance, specify your sourcemap service URL:

- name: Upload Sourcemaps
  uses: faststats-dev/upload-sourcemaps@v0.2
  with:
    dist-dir: dist
    api-key: ${{ secrets.FASTSTATS_SOURCEMAP_KEY }}
    api-url: https://sourcemaps.your-domain.com

Managing Sourcemaps

View and manage uploaded sourcemaps in Project Settings → Sourcemaps:

• Uploaded Sourcemaps: Lists all sourcemaps uploaded via the API with their file sizes
• Delete: Remove individual sourcemaps by hovering and clicking the trash icon
• Wipe All: Remove all uploaded sourcemaps at once
• Refresh: Reload the list to see recently uploaded files

Verifying Integration

Once configured, FastStats will automatically attempt to fetch and apply the sourcemap when a new error is captured. Successfully mapped errors will display:

• Original source file paths instead of bundled filenames
• Accurate line and column numbers
• A badge indicating which sourcemap was applied