Getting started
Teams & Admin
Uploading Source Maps

Uploading Source Maps

Adding a build step has lots of benefits: performance, security, new language features. One of the downsides though is that the compiled code can be obfuscated and difficult to debug.

Source maps exist to try and preserve the original debugging experience as best as possible.

Upload Process

For production use cases where sourcemaps may not be exposed publicly, we provide tooling for preemptively uploading sourcemaps to our servers so that when recordings are made, they can make use of these maps. We provide both a CLI command, and a Webpack plugin to make integrating this into your build process as easy as possible.


We recommend not using compression during the minification process. Mangling is fine, but compression can cause issues with how source maps are interpreted by Replay.

API Keys

We recommend using the REPLAY_API_KEY environment variable to set up the API for use in all of our following examples, but each also allows passing the key directly as an argument. API Keys are available in the Team Settings modal.


You can upload source maps using the upload-sourcemaps command in the replay CLI @replayio/replay.

The simplest usage will be running the following after your production JS build has finished

npx @replayio/replay upload-sourcemaps --group <Version or SHA> <buildOutputDir>

You must ensure that your build tool is configured to output sourcemaps into the build directory you provide.


The sourcemap-upload Webpack plugin is available on npm at @replayio/sourcemap-upload-webpack-plugin and you can explore the available options at sourcemap-upload-webpack-plugin (opens in a new tab) and sourcemap-upload (opens in a new tab).

The simplest usage will be to edit your webpack.config.js to include a new entry in the plugins array at the top level of the file, e.g.

const ReplaySourceMapUploadWebpackPlugin = require("@replayio/sourcemap-upload-webpack-plugin");
module.exports = {
  // ...
  // Ensure that Webpack has been configured to output sourcemaps.
  devtool: "source-map",
  // ...
  plugins: [
    // Enable our plugin to upload the sourcemaps once the build has completed.
    // This assumes NODE_ENV is how you distinguish production builds. If that
    // is not the case for you, you will have to tweak this logic.
    process.env.NODE_ENV === "production" 
      ? [new ReplaySourceMapUploadWebpackPlugin({
          filepaths: ["outputDir/"],
          group: "<A unique version string or git SHA>"
      : [],
  // ...

Keep in mind that your build output will now contain sourcemaps, so you should take care to ensure that these maps aren't also exposed on your production site.


NextJS uses Webpack internally, so the plugin above will also be used for NextJS, but the config that needs editing is next.config.js instead. NextJS's own documentation (opens in a new tab) is a good place to start and shows how to add Webpack plugins to your build process. You'll also need to enable production sourcemaps (opens in a new tab), so you'll end up with the following additional config in your next.config.js file:

module.exports = {
  productionBrowserSourceMaps: true,
  webpack: (config, { buildId, dev, isServer }) => {
    if (!dev && !isServer) {
        new ReplaySourceMapUploadWebpackPlugin({
          // If you've configured a custom build directory, this should
          // point to that directory.
          filepaths: [".next/"],
          // Potentially the 'buildId' argument here could be used.
          group: "<A unique version string or git SHA>",
      // 'productionBrowserSourceMaps' will output your sourcemaps
      // into the build directory, which can expose them from your
      // production server as well, so you will likely want to delete
      // the .map files once they have been uploaded.
      config.plugins.push((compiler) =>
        compiler.hooks.afterEmit.tapPromise("DeleteSourceMaps", () =>
    return config;

💡 In most cases it’s safe to not include the group field.

As mentioned, NextJS's buildId can be useful, but please see their docs (opens in a new tab) to ensure verify if it is a good fit for your application.


💡 If you are serving your site via Vercel, see their docs (opens in a new tab) for information on setting up the REPLAY_API_KEY environment variable.

Debugging problems

Each of these approaches will log the sourcemaps as they are uploaded so that you can validate that all of the files you expect are being detected. They each also have a verbose mode, either logLevel: "verbose" for the JS plugins, and --verbose for the CLI.

If you're feeling particularly adventurous, you can also run these with the DEBUG=recordreplay:sourcemap-upload environment variable set to enable tons of debug logging, though that will likely mostly be useful to pass along to us to work with you on any issues you may face.