Source Maps

Upload source maps to deobfuscate minified stack traces.

Why Source Maps?#

Production JavaScript is typically minified and bundled, resulting in unreadable stack traces like:

TypeError: Cannot read property 'n' of null
    at e.exports (main.a1b2c3.js:1:23456)

By uploading source maps, JustAnalytics translates these into readable traces:

TypeError: Cannot read property 'name' of null
    at processUser (src/utils/user.ts:42:15)

Uploading Source Maps#

Using the CLI#

Install the JustAnalytics CLI:

npm install -g @justanalyticsapp/cli

Upload source maps after your build step:

justanalytics sourcemaps upload \
  --site-id YOUR_SITE_ID \
  --api-key YOUR_API_KEY \
  --release "1.0.0" \
  --directory ./dist

CI/CD Integration#

Add to your build pipeline:

# GitHub Actions example
- name: Upload source maps
  run: |
    npx @justanalyticsapp/cli sourcemaps upload \
      --site-id ${{ secrets.JA_SITE_ID }} \
      --api-key ${{ secrets.JA_API_KEY }} \
      --release ${{ github.sha }} \
      --directory ./dist

Webpack Plugin#

For automatic upload during build:

// webpack.config.js
const { JustAnalyticsSourceMapPlugin } = require('@justanalyticsapp/cli/webpack');

module.exports = {
  plugins: [
    new JustAnalyticsSourceMapPlugin({
      siteId: process.env.JUSTANALYTICS_SITE_ID,
      apiKey: process.env.JUSTANALYTICS_API_KEY,
      release: process.env.BUILD_VERSION,
    }),
  ],
};

Release Tagging#

When uploading source maps, always include a release tag that matches the data-release attribute on your monitoring script:

<script
  defer
  src="https://justanalytics.app/monitor.js"
  data-site-id="YOUR_SITE_ID"
  data-release="1.0.0"
></script>

JustAnalytics matches errors to source maps using the release tag.

Security#

Source maps are stored securely and are never exposed to end users. They are only used server-side to deobfuscate stack traces for your team.

To prevent source maps from being accessible in production, ensure your build process removes .map files from your public deployment or configures your server to block access to them.

Deleting Source Maps#

Remove source maps for old releases:

justanalytics sourcemaps delete \
  --site-id YOUR_SITE_ID \
  --api-key YOUR_API_KEY \
  --release "1.0.0"