Using Sentry with NodeJS and TypeScript

Sometimes SaaS products go wrong, and times like that we want to know what went wrong and why. We at Gradient use Sentry for real-time crash reporting for both our frontend and backend applications.

We use TypeScript on both the frontend (Angular) and the backend (Nodejs) so it’s quite important that we can get our sourcemaps up to Sentry and have them properly linked together, otherwise many of our errors become fairly useless! We’ve had a number of issues getting sourcemaps to link up properly, in part due to the documentation but also due to the Sentry command line application. I thought I’d share how we use Sentry with TypeScript sourcemaps in production in the hopes it might help you get it working as well. It’s important to know that Sentry’s sourcemap and TypeScript support is very new and likely to improve a lot over the coming months.

Preparing your application

1. The first thing to do is to pull down raven (Sentry’s nodejs module) along with the corresponding types. You can do this with npm or yarn, but we use yarn.

$ yarn add raven --exact
$ yarn add @types/raven --dev --exact

2. Now you’ll need to configure Raven, this requires two things to be done. First, you’ll need to push in your Sentry release version and then you’ll need to create a dataCallback which will help to format our error before shipping it up to Sentry.

Here’s is an example that integrates Sentry into ExpressJS server, be aware that you may need to insert your own middleware and other configurations in between. Just ensure that you keep all of the Sentry code in the correct order.

Once you’ve done that, make sure to set your version in the package.json to what your next release will be, we’ll use the example of 1.0.0.

Tagging git and creating the Sentry release

Now our application is ready, we can make the Sentry release. This is a three-step process and assumes you’re using git and the Sentry CLI.

1. Ensure all of your work is committed (such as bumping your version number).
2. Create a git tag which must be the same as the value you’ve passed into Sentry, in our this case we’ve used our package.json version value which for our example is 1.0.0. This means our tag command will be similar to the following

$ git tag 1.0.0
$ git push origin master --tags

3. Finally, we need to make the Sentry release with the CLI commands, I’ll be honest and say the CLI API doesn’t make this easy and it’s pretty cryptic. There may be a better process for this but this is what we figured from the documentation. For this we use the Sentry CLI, you’ll need to plumb in your respective organisation and project into the -o and -p flags, I’m using placeholders in this example.

$ sentry-cli releases -o gradient -p our-proj new 1.0.0
$ sentry-cli releases -o gradient -p our-proj files 1.0.0 upload-sourcemaps ./dist
$ sentry-cli releases -o gradient -p our-proj set-commits --auto 1.0.0
$ sentry-cli releases -o gradient -p our-proj finalize 1.0.0

The two important bits of this is that the version numbers are correct, and that the location of your sourcemaps is correct. In this example, the TypeScript sourcemaps reside in ./dist but yours may be elsewhere.

Now you can deploy your code our with Sentry ready and waiting to receive any error events. Sentry will convert your stack traces over to use your applications generated sourcemaps. An important thing to note, you do not need to deploy your sourcemaps onto your server for this to work. The second command in the above block uploads the sourcemaps directly to Sentry. You can find those under the Artefacts tab of your release if needed.