Skip to main content
sylphx

Source Maps

Monitoring

Upload source maps to transform minified stack traces into readable code references. Debug production errors with full context.

Readable Stack Traces

Original file names, functions, and line numbers

CLI Upload

Simple command-line upload process

CI/CD Integration

Automatic upload in your pipeline

Release Tracking

Associate source maps with releases

Why Source Maps Matter

Modern JavaScript applications are minified and bundled for production. When an error occurs, the stack trace points to minified code that's nearly impossible to debug:

Without Source Maps
// Error stack trace from production:
TypeError: Cannot read property 'name' of undefined
    at o (main.a1b2c3d4.js:1:45678)
    at s (main.a1b2c3d4.js:1:45892)
    at HTMLButtonElement.<anonymous> (main.a1b2c3d4.js:1:46123)

// What does 'o' at position 45678 mean? 🤷

With source maps, Sylphx transforms this into readable stack traces:

With Source Maps
// Same error, symbolicated:
TypeError: Cannot read property 'name' of undefined
    at getUserProfile (src/api/users.ts:42:15)
    at handleProfileClick (src/components/UserCard.tsx:28:10)
    at onClick (src/components/Button.tsx:15:5)

// Now we know exactly where to look! ✅

Source Maps Are Secure

Source maps uploaded to Sylphx are stored securely and never exposed to end users. They're only used server-side to symbolicate stack traces.

Uploading Source Maps via CLI

The Sylphx CLI provides the simplest way to upload source maps after building your application.

1

Install the CLI

# Install globally
npm install -g @sylphx/cli

# Or use npx
npx @sylphx/cli --version
2

Configure Your Build

Ensure your build generates source maps:

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
}
3

Upload After Build

# Upload all source maps in the output directory
npx @sylphx/cli sourcemaps upload ./dist \
  --app-id your-app-id \
  --release v1.2.3

# With API key from environment
SYLPHX_API_KEY=your-api-key npx @sylphx/cli sourcemaps upload ./dist

CLI Options

PropertyTypeDescription
--app-idrequiredstringYour Sylphx application ID
--releaserequiredstringRelease version (e.g., v1.2.3, git SHA)
--api-keystringAPI key (or use SYLPHX_API_KEY env var)
--url-prefixstring= "~/"URL prefix for source files
--includestring= "**/*.map"Glob pattern for files to include
--ignorestringGlob pattern for files to ignore
--dry-runboolean= falseList files without uploading
--validateboolean= trueValidate source maps before upload

Automatic Upload in CI/CD

Integrate source map uploads into your deployment pipeline to ensure every release is symbolicated.

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload source maps
        run: |
          npx @sylphx/cli sourcemaps upload .next \
            --app-id ${{ secrets.SYLPHX_APP_ID }} \
            --release ${{ github.sha }}
        env:
          SYLPHX_API_KEY: ${{ secrets.SYLPHX_API_KEY }}

      - name: Deploy
        run: npm run deploy

      # Optional: Delete source maps after upload
      - name: Remove source maps from bundle
        run: find .next -name "*.map" -delete

Don't Ship Source Maps

Remove source maps from your production bundle after uploading to Sylphx. This prevents exposing your source code to end users while still enabling symbolication.

Symbolicating Stack Traces

Once source maps are uploaded, Sylphx automatically symbolicates incoming error stack traces. Here's how it works:

Error captured with minified stack trace
Release version extracted from error report
Matching source maps retrieved from storage
Stack frames mapped to original source locations
Symbolicated stack trace displayed in dashboard

Setting the Release Version

For symbolication to work, the release version in your error reports must match the version used when uploading source maps:

// app/providers.tsx
'use client'

import { SylphxProvider } from '@sylphx/sdk/react'

export function Providers({ children }) {
  return (
    <SylphxProvider
      appId={process.env.NEXT_PUBLIC_SYLPHX_APP_ID!}
      release={process.env.NEXT_PUBLIC_RELEASE_VERSION}
      // Or use git commit SHA
      // release={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA}
    >
      {children}
    </SylphxProvider>
  )
}

Handling Multiple Releases

Sylphx stores source maps for multiple releases, allowing you to debug errors from any version of your application.

Release Retention

Configure how long source maps are retained:

Retention Settings
// Settings > Monitoring > Source Maps
{
  "retention": {
    "maxReleases": 50,           // Keep last 50 releases
    "maxAge": "90d",             // Or releases from last 90 days
    "keepLatest": true,          // Always keep the latest release
    "deleteOnRollback": false    // Keep source maps even after rollback
  }
}

Managing Releases

# List all releases with source maps
npx @sylphx/cli sourcemaps list --app-id your-app-id

# Output:
# Release          Uploaded        Files   Size
# v1.2.3           2 hours ago     45      12.3 MB
# v1.2.2           3 days ago      44      12.1 MB
# v1.2.1           1 week ago      44      12.0 MB

# Delete source maps for a specific release
npx @sylphx/cli sourcemaps delete --app-id your-app-id --release v1.2.1

# Delete all source maps older than 30 days
npx @sylphx/cli sourcemaps prune --app-id your-app-id --older-than 30d

Verifying Source Map Upload

After uploading, verify that your source maps are correctly configured:

# Validate source maps before upload
npx @sylphx/cli sourcemaps validate ./dist

# Output:
# Validating source maps in ./dist...
# ✓ main.a1b2c3d4.js.map - Valid (sources: 45, mappings: OK)
# ✓ vendor.e5f6g7h8.js.map - Valid (sources: 128, mappings: OK)
# ✗ worker.i9j0k1l2.js.map - Invalid (missing sources)
#
# 2 valid, 1 invalid

# Verify upload was successful
npx @sylphx/cli sourcemaps verify --app-id your-app-id --release v1.2.3

# Output:
# Release: v1.2.3
# Status: Complete
# Files uploaded: 45
# Total size: 12.3 MB
# Uploaded at: 2024-01-15T10:30:00Z

Test Symbolication

Send a test error to verify symbolication is working:

# Send a test error
npx @sylphx/cli test-error --app-id your-app-id --release v1.2.3

# This will:
# 1. Send a test error with a minified stack trace
# 2. Wait for symbolication to complete
# 3. Display the symbolicated result

# Output:
# ✓ Test error sent
# ✓ Symbolication complete
#
# Original:
#   at o (main.a1b2c3d4.js:1:45678)
#
# Symbolicated:
#   at testFunction (src/test.ts:10:5)

Troubleshooting

Common issues and solutions:

Stack traces not symbolicated

Ensure the release version in error reports matches the upload. Check that source maps were uploaded successfully.

Missing source files

Source maps must include original source content or sources must be accessible. Use --validate to check.

URL prefix mismatch

The --url-prefix must match how files are referenced in your bundle. Use ~/path for relative paths.

Upload fails in CI

Ensure SYLPHX_API_KEY is set as a secret. Check that the build outputs source maps.

Debug Mode

Run the CLI with --debug flag to see detailed logs and troubleshoot upload issues.

Best Practices

Use semantic versioning

Version your releases consistently (v1.2.3 or git SHA) for easy tracking.

Upload before deploy

Upload source maps before deployment so errors are symbolicated immediately.

Remove maps from production

Delete .map files from your deployed bundle to keep source code private.

Validate in CI

Add validation step in CI to catch source map issues before deployment.

Monitoring Overview

Learn about error tracking basics

Error Grouping

Configure error fingerprinting