Skip to main content
Modern JavaScript is minified and bundled for production, making stack traces unreadable. Proliferate uses source maps to show you the original source code when viewing errors.

​
Why Source Maps?

Error: Cannot read property 'id' of undefined
    at e.value (main.a3f2e1d4.js:1:23456)
    at t.render (main.a3f2e1d4.js:1:34567)

​
Uploading Source Maps

The easiest way to upload source maps is via our build plugins. They automatically:
  1. Detect the release version (from git or CI environment)
  2. Upload source maps during your build
  3. Associate them with the correct release

Next.js

For Next.js applications

Webpack

For Webpack builds

Vite

For Vite applications

​
Using the CLI

For more control, use the CLI to upload source maps manually: 
# Install the CLI
npm install -g @proliferate/cli

# Upload source maps for a release
proliferate sourcemaps upload \
  --release $(git rev-parse HEAD) \
  --api-key $PROLIFERATE_API_KEY \
  ./dist

​
Using the API

For custom build systems, use the API directly: 
# Create a release
curl -X POST https://api.proliferate.com/api/v1/releases \
  -H "Authorization: Bearer $PROLIFERATE_API_KEY" \
  -F "version=$(git rev-parse HEAD)" \
  -F "url_prefix=~/"

# Upload source maps
curl -X POST https://api.proliferate.com/api/v1/sourcemaps \
  -H "Authorization: Bearer $PROLIFERATE_API_KEY" \
  -F "release=$(git rev-parse HEAD)" \
  -F "url=~/static/js/main.js" \
  -F "sourcemap=@./dist/static/js/main.js.map"

# Finalize the release
curl -X POST "https://api.proliferate.com/api/v1/releases/$(git rev-parse HEAD)/finalize" \
  -H "Authorization: Bearer $PROLIFERATE_API_KEY"

​
Release Management

​
What is a Release?

A release is a version identifier (typically a git commit SHA) that ties source maps to specific deployed code. When an error is captured, the SDK includes the release version, allowing Proliferate to look up the correct source maps.

​
Release Workflow

1

Create Release

The release is created automatically when you start uploading source maps
2

Upload Source Maps

Upload all .map files for your JavaScript bundles
3

Finalize Release

Mark the release as complete (optional but recommended)

​
Auto-Detection

The SDK automatically detects release versions from:
  1. Build plugin injection: __PROLIFERATE_RELEASE__ global variable
  2. Environment variables: PROLIFERATE_RELEASE, GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, and others
Or set it explicitly: 
Proliferate.init({
  endpoint: 'https://api.proliferate.com/api/v1/errors',
  apiKey: 'pk_your_api_key',
  release: '1.2.3',  // or git commit SHA
});

​
How Resolution Works

When viewing an error in the dashboard:
  1. Match release: Find source maps for the error’s release version
  2. Match URL: Find the source map for the minified file URL
  3. Resolve positions: Map minified line/column to original source
  4. Display: Show original file, function, and line number

​
URL Matching

Source maps are matched using URL prefixes. The default prefix is ~/, which matches relative URLs: 
// Source map uploaded with url: "~/static/js/main.js"
// Matches error at: "https://myapp.com/static/js/main.js"
// Matches error at: "https://staging.myapp.com/static/js/main.js"

​
CI/CD Integration

- name: Build
  run: npm run build

- name: Upload Source Maps
  run: |
    npx @proliferate/cli sourcemaps upload \
      --release ${{ github.sha }} \
      --api-key ${{ secrets.PROLIFERATE_API_KEY }} \
      ./dist

​
Troubleshooting

  1. Check release version: Ensure the SDK’s release matches the uploaded source maps 
    console.log('Release:', __PROLIFERATE_RELEASE__);
  2. Check URL matching: Verify the minified file URL matches the uploaded source map URL 
    proliferate releases list
proliferate sourcemaps list --release <version>
  3. Verify source maps are valid: Test with source-map-cli 
    npx source-map-cli --map ./dist/main.js.map --position 1:23456
For very large bundles:
  1. Use code splitting to create smaller chunks
  2. Enable gzip compression in your build
  3. Consider using hidden-source-map if you don’t want inline source maps
Source maps contain your original source code. To keep them secure:
  1. Don’t serve source maps publicly: Use hidden-source-map webpack devtool
  2. Use environment variables: Never commit API keys to your repository
  3. Restrict API key permissions: Use separate keys for source map upload vs. error ingestion
// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',  // Creates .map files without reference in .js
};