Best Practices

A Simple Setup

In this simple project, the minified/transpiled files and their source maps reside in the same directory:

├── build/
│   ├── worker.js
│   ├── worker.js.map
│   ├── app.js
│   ├── app.js.map
│   ├── index.html
├── package.json
├── public/
│   └── index.html
├── sentry.properties
├── src/
│   ├── app.js
│   └── worker.js
├── webpack.config.js

For this project, we can use a simple Sentry configuration:

const SentryWebpackPlugin = require("@sentry/webpack-plugin");
// ...
plugins: [
  new SentryWebpackPlugin({
    authToken: process.env.SENTRY_AUTH_TOKEN,
    org: "example-org",
    project: "example-project",
    include: "build",
    configFile: "sentry.properties",
    release: process.env.SENTRY_RELEASE,
  }),
],
// ...

We recommend using the Webpack plugin to integrate your source maps into Sentry. You can use Sentry CLI if you are not using Webpack in your project.

Consistent Release

For Sentry to associate error stack traces with your source maps, define your release number as a Webpack plugin option or a Sentry CLI argument (whichever you use). If you are using Sentry CLI, you should also define the same release number in your Sentry.init() call. The easiest way to assure consistency of the release number is to set it as an environment variable in your project:

# ...
SENTRY_RELEASE="1.2.3"
# ...

Then, if you are using sentry-webpack-plugin:

// ...
new SentryWebpackPlugin({
  // ... other options
  release: process.env.SENTRY_RELEASE,
});
// ...

Or, if you are using Sentry CLI:

sentry-cli releases new "$SENTRY_RELEASE"
sentry-cli releases files "$SENTRY_RELEASE" upload-sourcemaps /path/to/sourcemaps

Correct Source Paths

The filenames of your release artifacts (bundle files and source maps) should match with the reported paths in stack traces. You can use upload configuration to adjust the names of your files. Both the Webpack plugin and Sentry CLI have the same options; those relevant to source maps are covered below. It's also possible to adjust the paths inside your stack traces using our RewriteFrames integration.

Options for Webpack and Sentry CLI

These options and examples will help integrate your source maps.

include

This option accepts one or more paths to scan recursively for sources and *.map files. For example:

1. Including from where your transpiler/bundler outputs files:

• include: './app/.next'
• include: './build'

2. Including from multiple folders:

• include: ['./src', './lib']

3. Recursively searching the entire project:

• include: '.'

rewrite

Enables rewriting of matching source maps so that indexed maps are flattened and missing sources are inlined if possible. Defaults to true.

This option should be enabled for stripPrefix and stripCommonPrefix to work.

urlPrefix

This option adds a common prefix to the beginning of all filenames. Defaults to ~/, which is a wildcard that matches any scheme and hostname (the http://my.web.site/ part of http://my.web.site/path/to/script.js).

This option is useful when the entry point of the application (generally index.html for the browser side and index.js for Node) is one or more levels above the source/source map files, as in this example:

├── build/
│   ├── index.html
│   ├── static/
│   │   ├── app.js
│   │   ├── app.js.map

In this case, configure as in the following example:

// ...
new SentryWebpackPlugin({
  // ...
  include: "build/static/",
  urlPrefix: "~/static/"
  // ...
}),
// ...

stripPrefix

This option removes the given prefix from filenames as referenced from within a sourcemap (in the sources entry, for instance). This is useful when you need to trim extra prefixes that your bundler/development server may add to your filenames, such as webpack://_N_E/.

Note that using the stripPrefix option will not change the names of your uploaded files. When you have the parent folders of your target files as unwanted prefixes, include the portion you want stripped in your include Webpack plugin option or in the path/to/sourcemaps passed to sentry-cli. For example, if your files are stored in ./build/static/js/ and you have include: "build" in your Webpack plugin configuration, your files will be uploaded with names like ~/static/js/bundle.js. If you update your configuration to include: "build/static/js", your files will upload as ~/bundle.js (and so on) instead.

Adjusting Frames

Optionally, you can use Sentry's RewriteFrames integration to fine-tune the paths inside your stack traces.

import { RewriteFrames } from "@sentry/integrations";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    new RewriteFrames({
      // ... options
    }),
  ],
});