Error Debugging

When there are any production errors it is difficult to debug as the stack trace is minified, to solve this problem upload source maps files to Middleware which allows you to see the original source code and stack trace of the errors that occur in your minified or transpiled code.

Uploading Source Maps

CLI

1. Install Middleware sourcemap uploader

First install the Middleware sourcemap uploader in your project. The uploader will allow you to specify which files to upload as sourcemaps for a given release.

npm install -g @middleware.io/sourcemap-uploader

2. Enable Source Maps in your build

If you haven't already, you'll need to enable source maps in your build process.

For example, if you're using Webpack, you can enable source maps by setting the devtool option to source-map in your Webpack configuration.

module.exports = {
  devtool: "source-map",
};

In Next.js, you can enable source maps by setting the productionBrowserSourceMaps to true in your next.config.js.

module.exports = {
  productionBrowserSourceMaps: true,
};

3. Uploading source maps after building

Next, after your build step you'll want to point the sourcemap uploader to the directory containing your source maps and call the upload-sourcemaps command with your account key (this is a different key from your middleware API key). You can find your key in the installation page in your dashboard.

sourcemap-uploader upload
    --apiKey=<rum_account_key>
    --path="/path/to/sourcemaps"
    --appVersion="1.0.0"

Sourcemap-uploader Arguments

apiKey

The API key for your project. You can find this in the installation page in your dashboard.

path

The path that middleware will use to send .map files. The default value is current directory.

appVersion

The version of your current deployment. Please provide the same app.version value in defaultAttributes as the value you provide for version in Middleware.track. This ensures that we're always using the same set of sourcemaps for your current bundle. If omitted, sourcemaps are uploaded as latest.

Removing Sourcemaps from Build Directory

After building source maps, you may want to remove the maps and the sourcemap references from your production build. To do so, you can run the following commands after the source map upload command to remove all source maps and references:

# Delete source maps
find /path -type f -name '*.js.map' -delete
find /path -type f -name '*.css.map' -delete

# Delete source map references
find /path -type f -name '*.js' -exec sed -i -E 's/sourceMappingURL=[^ ]*\.js\.map//g' {} +
find /path -type f -name '*.css' -exec sed -i -E 's/sourceMappingURL=[^ ]*\.css\.map//g' {} +

Webpack

You can upload sourcemap using Webpack plugin, available in @middleware.io/sourcemap-uploader/dist/webpack-plugin package.

To use the plugin, edit your webpack.config.js to include a new entry in the plugins array at the top level of the file, e.g.

const MiddlewareWebpackPlugin = require("@middleware.io/sourcemap-uploader/dist/webpack-plugin").default

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.

Webpack plugin options

Webpack plugin offers serveral options to configure searching sourcemaps and build artifacts on disk & configuring upload paths based on project structure.

This makes it clear that path is where you're uploading from, while basePath determines how the source maps will resolve original source file locations during error unminification.

Webpack plugin uploads sourcemaps to the workspace associated with your API key, and automatically matches up sourcemaps with the build artifacts in a error tracking screen when you debug it.

Next.js

Next.js uses Webpack internally, so the plugin above will also be used for NextJS, but the config that needs editing is next.config.js instead. Next.js own documentation 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, so you'll end up with the following additional config in your next.config.js file:

const MiddlewareWebpackPlugin =
  require("@middleware.io/sourcemap-uploader/dist/webpack-plugin").default;

const nextConfig = {
  productionBrowserSourceMaps: true,

  webpack: (config) => {
    config.plugins.push(
      new MiddlewareWebpackPlugin(
        "<ACCOUNT_KEY>", // Account key of the application.

Also see the Next.js docs on "Configuring the Build ID" for details on generating a consistent build ID, such as with a Git hash.