Skip to main content
When your code is compiled or minified for production, stack traces become unreadable. Source maps allow Monocle to show you the original source code in error stack traces, making debugging much easier.

​
Prerequisites

Before uploading source maps, ensure your TypeScript compiler generates them. Add these options to your tsconfig.json: 
{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}
  • sourceMap: Generates .map files alongside your compiled JavaScript
  • inlineSources: Embeds the original TypeScript source in the source map (required to display code snippets in Monocle)

​
How It Works

  1. During your build process, source maps (.map files) are generated
  2. You upload these source maps to Monocle with a release version
  3. Your application reports the same version via APP_VERSION at runtime
  4. When an error occurs, Monocle matches the version and deobfuscates the stack trace
The --release version you use when uploading must match the APP_VERSION environment variable in your running application. If they don’t match, Monocle cannot map the minified code back to your source.

​
Upload Source Maps

​
Using the CLI

Upload source maps using the Monocle CLI: 
npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="1.0.0"

​
Options

OptionDescriptionRequired
--releaseRelease version (must match APP_VERSION)Yes
--api-keyMonocle API key (or use MONOCLE_API_KEY env var)Yes
--dry-runPreview what would be uploaded without uploadingNo

​
Environment Variables

Instead of passing --api-key, you can set the MONOCLE_API_KEY environment variable: 
export MONOCLE_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="1.0.0"

​
CI/CD Integration

Upload source maps after building your application, before deployment.

​
GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

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

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci
      - run: node ace build

      - name: Upload source maps
        run: npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="${{ github.sha }}"
        env:
          MONOCLE_API_KEY: ${{ secrets.MONOCLE_API_KEY }}

      # Deploy your application...

​
GitLab CI

deploy:
  stage: deploy
  script:
    - npm ci
    - node ace build
    - npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="$CI_COMMIT_SHA"
  variables:
    MONOCLE_API_KEY: $MONOCLE_API_KEY

​
Using Git SHA as Release Version

A common pattern is to use the git commit SHA as your release version. This ensures each deployment has a unique version: 
# In your deploy script
export APP_VERSION=$(git rev-parse HEAD)
npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="$APP_VERSION"
Make sure your application also uses the same git SHA for APP_VERSION: 
# .env or environment configuration
APP_VERSION=abc123def456...

​
Dry Run

Use --dry-run to preview what files would be uploaded without actually uploading them: 
npx @monocle.sh/cli sourcemaps upload "./build/**/*.map" --release="1.0.0" --dry-run
This is useful to verify your glob pattern matches the expected files before uploading.