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. The Flightcontrol platform will automatically upload source maps to Sentry for you if you use Nixpacks builds, and enable the integration.

Dashboard Configuration

In the Flightcontrol dashboard, you can find the Sentry option in the Integrations section of the Config tab for your Web Server or Worker service.

Look for the Upload Sentry source map option and toggle the checkbox.

This will only work with Nixpacks builds.

Flightcontrol.json Configuration

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 uploadSentrySourceMap key with either a true or false value.

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

Similar to the dashboard configuration, this will only work with Nixpacks builds.

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.

Deleting Source Maps after Uploading

In many cases, you may want to generate source maps for upload to Sentry, but not send them to production. This would be the case if you don't want your users to open up the web development console in their browser and view the original front end source code of your application.

One way to solve this problem is to add a postBuildCommand to your flightcontrol.json configration file that deletes the source maps after they are uploaded to Sentry. This will ensure that the source maps are not deployed to production.

The details of this command will depend on your specific project, but here is an example for a Redwood web project deployed to the /web/dist directory:

"postBuildCommand": "rm -rf ./web/dist/assets/*.map",

You can verify that your source maps have been deleted by checking the Build Logs for your Flightcontrol deployment and looking for the rm command in the output.

If you have any questions about this step, please reach out to us and we will be happy to help.