Agent skill

source-map-setup

Configure source maps for readable stack traces. Use when setting up error tracking, debugging production issues, or configuring build tools.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/nexus-labs-automation/web-observability/tree/main/skills/source-map-setup

SKILL.md

Source Map Setup

Make production stack traces readable by uploading source maps to your error tracking service.

Why Source Maps?

Without source maps:

TypeError: Cannot read property 'x' of undefined
    at e.render (main.a1b2c3.js:1:45678)
    at t.update (main.a1b2c3.js:1:12345)

With source maps:

TypeError: Cannot read property 'x' of undefined
    at ProductCard.render (src/components/ProductCard.tsx:45:12)
    at CartList.update (src/features/cart/CartList.tsx:78:8)

Build Tool Configuration

Vite

typescript
// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: {
    sourcemap: true, // Generate source maps
  },
  plugins: [
    sentryVitePlugin({
      org: 'your-org',
      project: 'your-project',
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: {
        filesToDeleteAfterUpload: ['**/*.map'], // Don't deploy maps
      },
    }),
  ],
});

Webpack (Next.js, CRA)

javascript
// next.config.js
const { withSentryConfig } = require('@sentry/nextjs');

module.exports = withSentryConfig(
  {
    // Your Next.js config
  },
  {
    org: 'your-org',
    project: 'your-project',
    silent: true,
    widenClientFileUpload: true,
    hideSourceMaps: true, // Don't expose in production
  }
);

esbuild

typescript
// esbuild.config.ts
import * as Sentry from '@sentry/esbuild-plugin';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  sourcemap: true,
  plugins: [
    Sentry.sentryEsbuildPlugin({
      org: 'your-org',
      project: 'your-project',
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

Rollup (SvelteKit)

javascript
// vite.config.ts (SvelteKit uses Vite)
import { sentrySvelteKit } from '@sentry/sveltekit';

export default defineConfig({
  plugins: [
    sentrySvelteKit({
      sourceMapsUploadOptions: {
        org: 'your-org',
        project: 'your-project',
        authToken: process.env.SENTRY_AUTH_TOKEN,
      },
    }),
    sveltekit(),
  ],
});

Vendor-Specific Setup

Sentry

bash
# Install CLI
npm install @sentry/cli --save-dev

# Upload manually (CI/CD)
sentry-cli sourcemaps upload \
  --org your-org \
  --project your-project \
  --release "1.0.0" \
  ./dist

Datadog

typescript
// datadog-ci upload
// In CI/CD:
// npx @datadog/datadog-ci sourcemaps upload ./dist \
//   --service your-service \
//   --release-version 1.0.0 \
//   --minified-path-prefix /static/js

New Relic

javascript
// newrelic.js
exports.config = {
  app_name: ['Your App'],
  browser_monitoring: {
    enable: true,
    debug: false,
  },
  // Source maps uploaded via CLI or agent
};

CI/CD Integration

GitHub Actions

yaml
# .github/workflows/deploy.yml
- name: Upload Source Maps
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx sentry-cli releases new ${{ github.sha }}
    npx sentry-cli sourcemaps upload \
      --release ${{ github.sha }} \
      --url-prefix '~/' \
      ./dist
    npx sentry-cli releases finalize ${{ github.sha }}

Vercel

javascript
// next.config.js - automatic with @sentry/nextjs
module.exports = withSentryConfig(nextConfig, {
  // Vercel automatically sets VERCEL_GIT_COMMIT_SHA
  release: process.env.VERCEL_GIT_COMMIT_SHA,
});

Security Considerations

Approach Pros Cons
Upload & delete Secure, no exposure Requires CI/CD setup
Hidden source maps Simple Still on server
Private source maps Full control Complex setup

Best practice: Upload to error tracking service, then delete from build output.

typescript
// Vite config
sentryVitePlugin({
  sourcemaps: {
    filesToDeleteAfterUpload: ['**/*.map'],
  },
});

Verification

bash
# Verify upload worked
sentry-cli releases files YOUR_RELEASE list

# Test with a real error
throw new Error('Test source maps');

Check in Sentry/Datadog that:

  1. Stack trace shows original file names
  2. Line numbers match source code
  3. Context code is visible

Common Issues

Issue Cause Fix
Still minified Maps not uploaded Check CI/CD logs
Wrong lines Version mismatch Ensure release matches
Missing files Incorrect path prefix Set --url-prefix correctly
Partial mapping Tree shaking Upload all chunks

Related Skills

  • See skills/error-tracking for error capture
  • See skills/bundle-performance for build optimization

References

  • references/frameworks/*.md - Framework-specific setup
  • references/platforms/*.md - Vendor-specific guides

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

nexus-labs-automation/web-observability

user-journey-tracking

Track user journeys with intent context and friction signals. Use when instrumenting funnels or multi-step flows.

0 0
Explore
nexus-labs-automation/web-observability

bundle-performance

Monitor JavaScript bundle size and execution performance. Use when tracking bundle size, identifying large chunks, or optimizing load performance.

0 0
Explore
nexus-labs-automation/web-observability

hydration-performance

Measure SSR hydration timing and issues. Use when tracking hydration performance, debugging hydration mismatches, or optimizing SSR/SSG applications.

0 0
Explore
nexus-labs-automation/web-observability

error-tracking

Set up error tracking with actionable context. Use when configuring error capture or error boundaries.

0 0
Explore
nexus-labs-automation/web-observability

route-transition-tracking

Measure time from navigation to page fully loaded and interactive. Use when tracking SPA navigation, route changes, or slow page transitions.

0 0
Explore
nexus-labs-automation/web-observability

synthetic-monitoring

Set up synthetic monitoring with Lighthouse CI and Playwright. Use when implementing automated performance testing, CI/CD performance gates, or proactive monitoring.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results