TypeScript (tsc)

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

Automatic Setup

The easiest way to configure uploading source maps with tsc and sentry-cli is by using the Sentry Wizard:

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 manually instead, follow the steps below.

Manual Setup

1. Generate Source Maps

First, configure the TypeScript compiler to output source maps:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,

    // Set `sourceRoot` to  "/" to strip the build path prefix from
    // generated source code references. This will improve issue grouping in Sentry.
    "sourceRoot": "/"
  }
}

2. Configure Sentry CLI

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

SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

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 What are Artifact 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:

...
//# debugId=<debug_id>
//# sourceMappingURL=<sourcemap_url>

Source maps should contain a field named debug_id like:

{
    ...
    "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

Associating dist with Artifact Bundle

In addition to release, you can also add a dist to your uploaded artifacts, to set the distribution identifier for uploaded files. To do so, run the sourcemaps upload command with the additional --dist option.

The distribution identifier is used to distinguish between multiple files of the same name within a single release. dist can be used to disambiguate build or deployment variants.

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:

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 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.

Dealing with TSLib

During compilation, if needed, TypeScript will inject some of its runtime dependencies into the output files it produces. It can include things like polyfills for function generators or some APIs not available in all the environments.

However, this makes it impossible to map frames from compiled code to the original sources, as there are no original sources.

We can still make it work, though. To do this, we need to tell the TypeScript compiler not to inject those code snippets and use its own 3rd party package called tslib, which is internally the part of a compiler.

The only things that have to change are inside the TypeScript config file, not your source code.

First, make sure that tslib is listed as the dependency in your package.json file. Once that's done, add two entries in compilerOptions section of your tsconfig.json. "noEmitHelpers": true and "importHelpers": true. That's it. Now, we can correctly map the source maps for all your stack trace frames, including internal TypeScript compiler code snippets.