Skip to content

Commit 00ec2be

Browse files
Luca Forstnervivianyentransmeubankgetsantry[bot]
authored
Add source maps upload instructions for CRA (#7628)
Co-authored-by: vivianyentran <20403606+vivianyentran@users.noreply.github.com> Co-authored-by: Steven Eubank <47563310+smeubank@users.noreply.github.com> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
1 parent 653ac38 commit 00ec2be

File tree

11 files changed

+141
-7
lines changed

11 files changed

+141
-7
lines changed

‎src/includes/sourcemaps-create-react-app.mdx

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
<Include name="debug-id-requirement.mdx" />
2+
3+
## Automatic Setup
4+
5+
The easiest way to configure uploading source maps with Sentry CLI is by using the Sentry Wizard:
6+
7+
<Include name="sourcemaps-wizard-instructions.mdx" />
8+
9+
If you want to configure source maps upload with the CLI manually instead, follow the steps below.
10+
11+
## Manual Setup
12+
13+
### 1. Generate Source Maps
14+
15+
Verify that you are generating source maps when building your React app.
16+
This should already be the case, unless you set the `GENERATE_SOURCEMAPS` environment variable to "false".
17+
18+
**Make sure to run a production build.**
19+
In the next steps we will modify and upload the artifacts that were generated during the build.
20+
Running a development build will not emit the necessary files.
21+
22+
### 2. Configure Sentry CLI
23+
24+
Install Sentry CLI as a dev-dependency with the package manager of your choice:
25+
26+
```bash {tabTitle:npm}
27+
npm install @sentry/cli --save-dev
28+
```
29+
30+
```bash {tabTitle:Yarn}
31+
yarn add @sentry/cli --dev
32+
```
33+
34+
```bash {tabTitle:pnpm}
35+
pnpm add @sentry/cli --save-dev
36+
```
37+
38+
<Note>
39+
40+
For more info on `sentry-cli` configuration visit the [Sentry CLI configuration docs](/product/cli/configuration/).
41+
42+
</Note>
43+
44+
Make sure `sentry-cli` is configured for your project. For that you can use environment variables:
45+
46+
<SignInNote />
47+
48+
<OrgAuthTokenNote />
49+
50+
```bash {filename:.env}
51+
SENTRY_ORG=___ORG_SLUG___
52+
SENTRY_PROJECT=___PROJECT_SLUG___
53+
# Auth tokens can be obtained from
54+
# https://sentry.io/settings/auth-tokens/
55+
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
56+
```
57+
58+
### 3. Inject Debug IDs Into Build Artifacts
59+
60+
Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file.
61+
Visit [What are Artifact Bundles](/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) if you want to learn more about Artifact Bundles and Debug IDs.
62+
63+
To inject Debug IDs, use the following command **every time after building your application**:
64+
65+
```bash
66+
sentry-cli sourcemaps inject /path/to/build
67+
```
68+
69+
Make sure to replace `/path/to/build` with the actual path where your build output is generated.
70+
In a Create React App application, this is usually the `build` folder.
71+
72+
#### Verify Debug IDs Were Injected Into Build Artifacts
73+
74+
After running the `sentry-cli sourcemaps inject` command, minified source files should contain a `debugId` comment at the end:
75+
76+
```javascript {filename:exampleMinifiedFile.js}
77+
...
78+
//# debugId=<debug_id>
79+
//# sourceMappingURL=<sourcemap_url>
80+
```
81+
82+
Source maps should now contain a field named `debug_id`:
83+
84+
```json {filename:exampleSourceMap.js.map}
85+
{
86+
...
87+
"debug_id":"<debug_id>",
88+
...
89+
}
90+
```
91+
92+
### 4. Upload Artifacts
93+
94+
After you've injected Debug IDs into your artifacts, upload them using the following command:
95+
96+
```bash
97+
sentry-cli sourcemaps upload /path/to/build
98+
```
99+
100+
#### Verify That Artifact Bundles Were Uploaded
101+
102+
Open up Sentry and navigate to **Project Settings > Source Maps**.
103+
If you choose “Artifact Bundles” in the tabbed navigation, you'll see all the artifact bundles that have been successfully uploaded to Sentry.
104+
105+
### 5. Deploy Your Application
106+
107+
If you're following this guide from your local machine, then you've successfully:
108+
109+
1. Generated minified source and source map files (artifacts) by running your application's build process
110+
2. Injected Debug IDs into the artifacts you've just generated
111+
3. Uploaded those artifacts to Sentry with our upload command
112+
113+
The last step is deploying a new version of your application using the generated artifacts you created in step one.
114+
**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.

‎src/platform-includes/sourcemaps/overview/javascript.mdx

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ The easiest way to configure uploading source maps is by using the Sentry Wizard
66

77
If you want to configure source maps upload manually, follow the guide for your bundler or build tool below.
88

9+
<PlatformSection supported={["javascript.react"]}>
10+
11+
### Create React App
12+
13+
If you used Create React App to set up your React application see our <PlatformLink to="/sourcemaps/uploading/create-react-app/">Create React App</PlatformLink> guide to upload source maps.
14+
15+
</PlatformSection>
16+
917
### Sentry Bundler Support
1018

1119
- <PlatformLink to="/sourcemaps/uploading/webpack/">Webpack</PlatformLink>

‎src/platform-includes/sourcemaps/upload/create-react-app/javascript.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
In this guide, you'll learn how to upload source maps for Create React App using our `sentry-cli` tool.
2+
3+
<Include name="sourcemaps-create-react-app.mdx" />

‎src/platforms/javascript/common/sourcemaps/uploading/cli.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Sentry CLI
33
description: "Upload your source maps using Sentry CLI."
4-
sidebar_order: 8
4+
sidebar_order: 6
55
---
66

77
<PlatformContent includePath="sourcemaps/upload/cli" />

‎src/platforms/javascript/common/sourcemaps/uploading/create-react-app.mdx

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Create React App
3+
description: "Upload source maps using Create React App and Sentry CLI."
4+
sidebar_order: 7
5+
supported:
6+
- javascript.react
7+
---
8+
9+
<PlatformContent includePath="sourcemaps/upload/create-react-app" />

‎src/platforms/javascript/common/sourcemaps/uploading/esbuild.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: esbuild
33
description: "Upload your source maps with the Sentry esbuild Plugin."
4-
sidebar_order: 5
4+
sidebar_order: 4
55
---
66

77
<PlatformContent includePath="sourcemaps/upload/esbuild" />

‎src/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Hosting Publicly
33
description: "Learn about publicly hosting your source maps, including how to address various security concerns."
44
redirect_from:
55
- /platforms/javascript/sourcemaps/hosting-publicly/
6-
sidebar_order: 9
6+
sidebar_order: 10
77
---
88

99
<Note>

‎src/platforms/javascript/common/sourcemaps/uploading/rollup.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Rollup
33
description: "Upload your source maps with the Sentry Rollup Plugin."
4-
sidebar_order: 3
4+
sidebar_order: 5
55
---
66

77
<PlatformContent includePath="sourcemaps/upload/rollup" />

‎src/platforms/javascript/common/sourcemaps/uploading/systemjs.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: SystemJS
33
description: "Upload your source maps using SystemJS and Sentry CLI."
4-
sidebar_order: 7
4+
sidebar_order: 9
55
notSupported:
66
- javascript.svelte
77
- javascript.sveltekit

‎src/platforms/javascript/common/sourcemaps/uploading/uglifyjs.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: UglifyJS
33
description: "Upload your source maps using UglifyJS and Sentry CLI."
4-
sidebar_order: 6
4+
sidebar_order: 8
55
notSupported:
66
- javascript.svelte
77
- javascript.vue

‎src/platforms/javascript/common/sourcemaps/uploading/vite.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Vite
33
description: "Upload your source maps with the Sentry Vite Plugin."
4-
sidebar_order: 4
4+
sidebar_order: 3
55
---
66

77
<PlatformContent includePath="sourcemaps/upload/vite" />

0 commit comments

Comments
 (0)