Create React App

Upload source maps using Create React App and Sentry CLI.

In this guide, you'll learn how to upload source maps for Create React App using our sentry-cli tool.

This guide assumes the following:

  • sentry-cli version >= 2.17.0
  • Sentry Javascript SDK version >= 7.47.0

The easiest way to configure uploading source maps with Sentry CLI is by using the Sentry Wizard:

Copied
npx @sentry/wizard@latest -i sourcemaps

The wizard will guide you through the following steps:

  • Logging into Sentry and selecting a project
  • Installing the necessary Sentry packages
  • Configuring your build tool to generate and upload source maps
  • Configuring your CI to upload source maps

If you want to configure source maps upload with the CLI manually instead, follow the steps below.

Verify that you are generating source maps when building your React app. This should already be the case, unless you set the GENERATE_SOURCEMAPS environment variable to "false".

Make sure to run a production build. In the next steps we will modify and upload the artifacts that were generated during the build. Running a development build will not emit the necessary files.

Install Sentry CLI as a dev-dependency with the package manager of your choice:

Copied
npm install @sentry/cli --save-dev

For more info on sentry-cli configuration visit the Sentry CLI configuration docs.

Make sure sentry-cli is configured for your project. For that you can use environment variables:

.env
Copied
SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. Visit What are Artifact Bundles if you want to learn more about Artifact Bundles and Debug IDs.

To inject Debug IDs, use the following command every time after building your application:

Copied
sentry-cli sourcemaps inject /path/to/build

Make sure to replace /path/to/build with the actual path where your build output is generated. In a Create React App application, this is usually the build folder.

After running the sentry-cli sourcemaps inject command, minified source files should contain a debugId comment at the end:

exampleMinifiedFile.js
Copied
...
//# debugId=<debug_id>
//# sourceMappingURL=<sourcemap_url>

Source maps should now contain a field named debug_id:

exampleSourceMap.js.map
Copied
{
    ...
    "debug_id":"<debug_id>",
    ...
}

After you've injected Debug IDs into your artifacts, upload them using the following command:

Copied
sentry-cli sourcemaps upload /path/to/build

Open up Sentry and navigate to Project Settings > Source Maps. If you choose “Artifact Bundles” in the tabbed navigation, you'll see all the artifact bundles that have been successfully uploaded to Sentry.

If you're following this guide from your local machine, then you've successfully:

  1. Generated minified source and source map files (artifacts) by running your application's build process
  2. Injected Debug IDs into the artifacts you've just generated
  3. Uploaded those artifacts to Sentry with our upload command

The last step is deploying a new version of your application using the generated artifacts you created in step one. We strongly recommend running everything you've configured above inside your CI/CD pipeline to ensure each subsequent deploy will have readable stack traces in Sentry error events.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").