Skip to main content
When viewing an error in the Proliferate dashboard, you can see the exact source code where the error occurred, with surrounding context to help you understand the problem.

​
How It Works

Source context is displayed when:
  1. Source maps are uploaded for the release
  2. GitHub integration is configured for the project
  3. The error includes a release/commit SHA
Error: Cannot read property 'id' of null
────────────────────────────────────────────
src/components/UserProfile.tsx:42

  40 │ function UserProfile({ user }) {
  41 │   // Get user details
→ 42 │   const userId = user.id;          ← Error here
  43 │   const userName = user.name;
  44 │
  45 │   return (
  46 │     <div className="profile">

[View in GitHub →]

​
Requirements

1

Upload Source Maps

Source maps must be uploaded for the release version:
# Upload source maps during build
proliferate sourcemaps upload \
  --release $(git rev-parse HEAD) \
  --api-key $PROLIFERATE_API_KEY \
  ./dist
See Source Maps for details.
2

Connect GitHub

Connect your GitHub repository to your Proliferate project:
  1. Go to Settings → Integrations
  2. Click Install GitHub App
  3. Select the repositories to grant access
  4. Link the repository to your project
3

Set Release Version

Errors must include a release version (commit SHA):
Proliferate.init({
  release: process.env.COMMIT_SHA,  // Or auto-detected
});

​
What You See

​
Stack Frame with Source

Each stack frame can show source context: 
at getUserId (src/utils/user.ts:42:15)
────────────────────────────────────────────

  39 │
  40 │ export function getUserId(user: User): string {
  41 │   // Validate user object
→ 42 │   return user.id;  // user was null!
  43 │ }
  44 │

[View in GitHub →]

​
Source Map Resolution

When source maps are available, minified locations are resolved to original source: 
Original (minified):
  at e.value (main.a3f2e1d4.js:1:23456)

Resolved:
  at getUserId (src/utils/user.ts:42:15)
Click View in GitHub to jump directly to the code: 
https://github.com/your-org/your-repo/blob/abc123/src/utils/user.ts#L42

​
Parsed Stack Trace

The stack trace is parsed to show:
FieldDescription
fileOriginal file path
lineLine number
columnColumn number
functionFunction name
resolved_fileSource-mapped file (if different)
resolved_lineSource-mapped line
can_fetch_sourceWhether source can be displayed
github_urlDirect link to GitHub

​
Configuration

​
Project Settings

Configure source context in project settings:
  1. GitHub Repository: Link to your code repository
  2. Source Path Prefix: Strip prefix from file paths (e.g., webpack://)

​
Source Path Prefix

If your source maps include webpack or other prefixes: 
Minified path: webpack:///./src/utils/user.ts
Source path prefix: webpack:///./
Result: src/utils/user.ts

​
Troubleshooting

Check source maps are uploaded:
proliferate releases list
proliferate sourcemaps list --release <version>
Check GitHub integration:
  • Verify repository is linked in Settings → Integrations
  • Ensure the GitHub App has access to the repository
Check release version:
  • Verify errors include the release field
  • Ensure release version matches uploaded source maps
Source map mismatch:
  • Rebuild and re-upload source maps
  • Verify the source map file matches the minified file
Path resolution issues:
  • Check source path prefix in project settings
  • Verify paths in source maps match your repository structure
Check URL matching:
  • Source map URL must match the error’s file URL
  • Check url_prefix configuration in build plugin
Verify source map format:
# Test source map resolution locally
npx source-map-cli --map ./dist/main.js.map --position 1:23456

​
Best Practices

Upload in CI/CD

# GitHub Actions example
- name: Build
  run: npm run build

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

Use Commit SHAs

Proliferate.init({
  release: process.env.GITHUB_SHA,
});

Keep Maps Private

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',
};

Configure Prefixes

// In project settings
Source Path Prefix: webpack:///./

​
Security

Source context uses read-only access to your repository. The GitHub App cannot modify your code.

​
What Data is Accessed

  • Repository contents: Only source files at specific commits
  • No credentials stored: GitHub App uses temporary installation tokens
  • Read-only access: Cannot modify your repository

​
Access Control

  • Only users with project access can view source context
  • Source is fetched on-demand, not stored permanently
  • GitHub access is per-organization, managed via the GitHub App

​
Sensitive Code

For sensitive code:
  1. Use .gitignore to exclude files
  2. Mark files as blocked in your source maps
  3. Configure the GitHub App to exclude specific paths