Publishing with source maps

When you build a web app for production, your source code is compiled, bundled, and often minified. The browser runs the transformed output — not the code you wrote. Source maps are files that connect that compiled output back to your original source.

Replay QA runs against your deployed app. When source maps are available, every analysis Replay performs — from tracing a failure through the call stack to pinpointing the line that caused a bug — can reference your original code. Without them, Replay is working with minified identifiers and compiled output.

What source maps unlock in Replay QA

More precise root cause analysis. When Replay time-travels a failing test recording, it traces the execution chain back to the source. With source maps, that trace cites your actual component names, function names, and file paths — not a(), b(), or chunk-abc123.js.

Actionable suggested fixes. Bug reports include suggested fixes with file and line references. Source maps ensure those references point to the right place in your codebase, so a coding agent or developer can act on them directly.

Better React analysis. Replay QA's React analysis layer — render tracking, performance profiling, effect analysis, render cause tracing — works without source maps for React itself. Your application's source maps let it report real component names and file locations instead of compiled identifiers. Results are best on React 19; React 18 users should upgrade if they can, or see the fallback below.

Configuring your build

Publicly served source maps — simplest, works automatically

If your app serves source maps publicly alongside the JS files, Replay QA discovers and uses them automatically via the sourceMappingURL references embedded in each bundle. No upload step needed.

Configure your build tool to emit and serve source maps:

• Next.js
• Vite
• Webpack

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  productionBrowserSourceMaps: true,
}

module.exports = nextConfig

Deploy with these settings and Replay QA will pick up the source maps on its own.

React 18 — upgrade to React 19 if you can

React 19 ships unminified production artifacts, so standard source maps work and React analysis is most accurate. React 18 shipped pre-minified builds with no source maps. Replay's React analysis still runs against React 18, but if you cannot upgrade and want the fullest results, the @acemarke/react-prod-sourcemaps package provides pre-built source maps for React 18's production artifacts and a build plugin that wires them in. See React Version Support for setup instructions.

Getting your coding agent to set this up

Paste the following prompt into your coding agent to have it configure source map emission for your project:

Configure this project to publish source maps so Replay QA can use them.

Check which bundler or framework is in use (Next.js, Vite, Webpack, etc.) and apply the appropriate setting to emit and publicly serve source maps:
- Next.js: set `productionBrowserSourceMaps: true` in next.config.js
- Vite: set `build.sourcemap: true` in vite.config.js
- Webpack: set `devtool: 'source-map'` in webpack.config.js

Replay QA discovers publicly served source maps automatically — no upload step is needed.

If the project uses React 18 (not React 19) and upgrading is not an option, also install @acemarke/react-prod-sourcemaps and configure it per the package README, so Replay's React analysis can read React's internal function names.

Make the minimum changes needed — don't restructure the build config beyond what's required.