Uploading Source Maps to Sentry

Flightcontrol can automatically upload JavaScript source maps (opens in a new tab) to Sentry for you.

This allows Sentry's stack traces to show the original JavaScript source code of your application instead of the minified version. Your production applications should be using a minified version of your code, so this is essential for debugging.

Integrating with Sentry

When you setup Sentry integration for your JavaScript web application project, there are two different steps that you need to do:

• Add the Sentry SDK to your Project
• Upload Source Maps to Sentry

When it comes to adding the Sentry SDK to your project, we suggest following the Sentry documentation (opens in a new tab) for your specific project. The Sentry documentation is very good, and they have instructions for all of the major JavaScript build tools (such as Webpack or Vite). This step is not specific to Flightcontrol.

The rest of this guide will focus on the second step: uploading source maps to Sentry. Flightcontrol has support in the platform for automatically uploading source maps to Sentry for you if you use Nixpacks builds.

Flightcontrol Configuration

Currently, support for Sentry source maps is only available when you configure with code (not the Dashboard) and use Nixpacks builds. Within your flightcontrol.json file, you can add the integrations object to one or more of your Flightcontrol services. The integrations object should contain an uploadSentryMap key with either a true or false value.

{
  "services": [
    {
      "name": "my-service",
      "integrations": {
        "uploadSentryMap": true
      }
    }
  ]
}

Sentry Environment Variables

The Flightcontrol integration with Sentry source map uploading requires the following environment variable to be set for your Flightcontrol environment:

• SENTRY_AUTH_TOKEN - This is the Sentry Auth token that the Sentry CLI Wizard generated for you. If you need a new one, you can create an Auth Token in the Settings/Project Name/Auth Tokens section of your Sentry dashboard.

There are two additional environment variables that you may want to set for your Sentry integration:

• SENTRY_SOURCE_MAPS_LOCATION - The location of the source maps that you want to upload to Sentry. This defaults to . (the current directory), but you may need to set this to ./dist or ./build.
• SENTRY_RELEASE_PREFIX - The prefix to use for the Sentry release. The Git commit SHA is used for the release tag, but you can set a prefix to help make your source maps more readable.

You may also want or need to set the following environment variables for your Sentry integration, if they aren't either already set or added to your source code by the Sentry wizard:

• SENTRY_DSN - The client key (DSN) for your Sentry project. You can find this in the Settings for your project in the Sentry dashboard.
• SENTRY_PROJECT - The name of the project that you are using for Sentry. You can find this in the Settings for your project in the Sentry dashboard.
• SENTRY_ORG - The organization slug that you are using for Sentry. You can find this in the Settings of your team's Sentry dashboard.

Flightcontrol sends the Git commit SHA to Sentry as the SENTRY_RELEASE tag.

Configuring your Project for Sentry

You do need to set up an account and project with Sentry. You can find Uploading Source Maps instructions on the Sentry docs website (opens in a new tab) for the various JavaScript build tools (such as Webpack or Vite).

The easiest way to get started with Sentry source maps is to use the Sentry wizard:

npx @sentry/wizard@latest -i sourcemaps

Follow the directions in the command line wizard, and Sentry will setup your project for you. It does a good job of auto-detecting the type of project you are using and configuring the project accordingly.

Make note of the SENTRY_AUTH_TOKEN secret that the wizard generates for you. You will need to add this to your Flightcontrol environment variables for the integration to work.

We recommend testing your Sentry integration locally before deploying to production with Flightcontrol to make sure that everything is working as expected.

Ensuring Source Maps are Uploaded

After making a successful deployment with Flightcontrol for your service, you can check the Flightcontrol Build Logs to make sure you see something similar to this output:

6:43:44 PM: #12 8.318 [sentry-vite-plugin] Info: Successfully uploaded source maps to Sentry
6:43:44 PM: #12 8.406 ✓ built in 7.50s
6:43:44 PM: #12 8.902 Created release fab7fb19d92dcef11e98d503e472e0b58ee82090
6:43:44 PM: #12 8.909 > Found 1 release file
6:43:44 PM: #12 8.910 > Analyzing 1 sources
6:43:44 PM: #12 8.971 > Rewriting sources
6:43:44 PM: #12 8.972 > Adding source map references
6:43:44 PM: #12 9.611 > Bundled 1 file for upload
6:43:44 PM: #12 9.904 > Uploaded release files to Sentry
6:43:44 PM: #12 10.00 > File upload complete (processing pending on server)
6:43:44 PM: #12 10.00 > Organization: ***
6:43:44 PM: #12 10.00 > Project: ***
6:43:44 PM: #12 10.00 > Release: fab7fb19d92dcef11e98d503e472e0b58ee82090
6:43:44 PM: #12 10.00 > Dist: None

Note the Bundled 1 file for upload line in the output. If something isn't working quite right, you may see 0 files for upload instead. If you see 0 files for upload, then the source maps were not uploaded to Sentry.

To confirm that source maps are uploaded, you can check your Sentry project. Take a look in the Settings page, then choose Projects from the sidebar menu. Choose your project, then look in the Source Maps tab in that sidebar menu. You should see an uploaded artifact build from your Flightcontrol project.

Troubleshooting

If you are having trouble getting source maps to upload to Sentry, you can check the Flightcontrol Build Logs to see if there are any errors. Look for entries related to Sentry uploads.

Flightcontrol will not even attempt to upload the source maps if the SENTRY_AUTH_TOKEN environment variable is not set. If you are not seeing any Sentry upload logs, make sure that you have set the SENTRY_AUTH_TOKEN environment variable for your Flightcontrol environment.