TypeScript (tsc)
In this guide, you'll learn how to successfully upload source maps using our sentry-cli
tool. This guide is only applicable if you're using tsc
to compile your project. If you use another tool (such as Webpack) in combination with TypeScript, visit our list of guides here.
This guide assumes the following:
sentry-cli
version >=2.17.0
- Sentry Javascript SDK version >=
7.47.0
Visit Uploading Source Maps without Debug IDs if you don't wish to update SDK or sentry-cli
versions.
1. Configure Sentry CLI
You can find installation instructions for Sentry CLI here: https://docs.sentry.io/product/cli/installation/
For more info on sentry-cli
configuration visit the Sentry CLI configuration docs.
Make sure sentry-cli
is configured for your project. You can use a .sentryclirc
file or environment variables:
Visit the auth token user settings page to find your auth tokens.
.sentryclirc
[auth]
token=your-auth-token
[defaults]
org=example-org
project=example-project
2. Generate Source Maps
Configure the TypeScript compiler to output source maps:
tsconfig.json
{
"compilerOptions": {
"sourceMap": true,
"inlineSources": true,
// Set `sourceRoot` to `/` to strip the build path prefix from
// generated source code references. This allows Sentry to match source files
// relative to your source root folder.
"sourceRoot": "/"
}
}
3. Inject Debug IDs Into Artifacts
Debug IDs are used to match the stack frame of an event with its corresponding minified source and source map file. Visit Artifact vs. Release bundles if you want to learn more about Artifact Bundles and Debug IDs.
To inject Debug IDs, use the following command:
sentry-cli sourcemaps inject /path/to/directory
Verify Debug IDs Were Injected in Artifacts
Minified source files should contain at the end a comment named debugId
like:
example_minified_file.js
...
//# debugId=<debug_id>
//# sourceMappingURL=<sourcemap_url>
Source maps should contain a field named debug_id
like:
example_source_map.js.map
{
...
"debug_id":"<debug_id>",
...
}
4. Upload Artifact Bundle
After you've injected Debug IDs into your artifacts, upload them using the following command.
sentry-cli sourcemaps upload /path/to/directory
Verify That Artifact Bundles Were Uploaded
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.
Optional Steps
Associating release
with Artifact Bundle
Provide a release
property in your SDK options.
Sentry.init({
// This value must be identical to the release name specified during upload
// with the `sentry-cli`.
release: "<release_name>",
});
Afterwards, run the sourcemaps upload
command with the additional --release
option. Please ensure that the value specified for <release_name>
is the same value specified in your SDK options.
sentry-cli sourcemaps upload --release=<release_name> /path/to/directory
Running upload
with --release
doesn't automatically create a release in Sentry. For that, you should create a release with the same name as a separate step in your pipeline or send the first event to Sentry with that release.
Associating dist
with Artifact Bundle
In addition to release
, you can also add a dist
to your uploaded artifacts. For that, run the sourcemaps upload
command with the additional --dist
option.
sentry-cli sourcemaps upload --release=<release_name> --dist=<dist_name> /path/to/directory
5. Deploy your Application
If you're following this guide from your local machine, then you've successfully:
- Generated minified source and source map files (artifacts) by running your application's build process
- Injected Debug IDs into the artifacts you've just generated
- 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 that you integrate sentry-cli
into your CI/CD Pipeline, to ensure each subsequent deploy will automatically inject debug IDs into each artifact and upload them directly to Sentry.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
- Package:
- npm:@sentry/react
- Version:
- 7.51.0
- Repository:
- https://github.com/getsentry/sentry-javascript