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.

<aside> 👉 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.

</aside>

API Keys

We recommend using the RECORD_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.

CLI

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.

Webpack

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 and sourcemap-upload.

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