Configure Sentry for Vue.JS project

Sentry is an awesome error reporting tool, that allows you to get notified if an error happens at runtime, either in your backend or frontend code. Getting stacktraces is hard for frontend since the code executes in the user’s browser, but Sentry catches and reports everything, including local variables and a bunch of other useful information. If you don’t use it yet, I encourage you to give it a try.

Step 1: catch errors

The official documentation is pretty good, here is a condensed version. I assume you already have an account, and created a project (you should have a “DSN” to give to the JS SDK). We will use Raven, which is Sentry’s SDK.

First, insert the following code at the beginning of your main.js entrypoint:

This snippet assumes you have a config.js file along your main.js , that contains application-wide configuration settings. Here is an example:

Sentry understands project releases, so we pass the release reference to Raven through an environment variable. This will enable features like “Mark this bug as resolved in the next release”, regression detection, etc.

Defining releases is also mandatory to be able to upload JS source maps.

The release is passed along to the JS code through an environment variable defined when running yarn build . For such variable to be passed, they must start with VUE_APP_ , hence the name VUE_APP_SENTRY_RELEASE .

So far, if you add a throw Error() (or a bug) somewhere in your code, deploy, and execute it on your production environment, you should see the error appear in your Sentry dashboard:

Sentry default view for a given JS error

Note that you can also define an environment (production, staging, etc) to help you filter issues and better understand the context. All you have to do is to add a line after line 18 in the first gist, with 'environment': 'staging', (although I recommend taking the value from a configuration file).

Step 2: source maps

Of course, JS bundles we upload to production servers are minified to save bandwidth. The resulting code is very very very (very) hard to read — try to understand the code in the previous screenshot. That’s why build tools (webpack in our case) usually generate a source map along the minified file, allowing browser or debugger to display the original code. To see nice stacktraces in Sentry, we need to send the source maps.

Sentry can automatically fetch source maps if they are publicly available and referenced in the bundled code, but I personally prefer another solution: upload them to Sentry. No need to bother protecting the source maps from people who would like to reverse engineer your application, plus it is super easy to actually upload them thanks to the Sentry webpack plugin.

Let’s install and configure the plugin:

Local configuration

1. Get a token from https://sentry.io/api/, with the scope “project:write”
2. Export your token with export SENTRY_AUTH_TOKEN=deadbeef or save it in a ~/.sentryclirc file (user-wide):

[auth]                        
token = your-token-here

Project configuration

Create a project-specific .sentryclirc file at the root of your project source tree (different from the previous one, which was located in your home folder), with the project information:

[defaults]
org=howfast
project=frontend

Note: org corresponds to your organization ID and project to… the project name (look at the URL https://sentry.io/<org>/<project>/issues/ in the dashboard).

The webpack plugin

1. Install the plugin: yarn add --dev @sentry/webpack-plugin
2. Update the webpack configuration to upload the source maps at each production build. You most likely created your project with vue-cli, so you don’t have direct access to the webpack configuration file, but vue-cli is flexible enough so you don’t have to eject. All you have to do is change the vue.config.js file to import and add the SentryPlugin:

const webpack = require('webpack');
const SentryPlugin = require('@sentry/webpack-plugin');
module.exports = {
  // generate sourceMap for production build?
  productionSourceMap: true,
  // tweak internal webpack configuration.
  // see https://github.com/vuejs/vue-cli/blob/dev/docs/webpack.md
  configureWebpack: {
    plugins: [
      ...
      new SentryPlugin({
        release: process.env.VUE_APP_SENTRY_RELEASE,
        include: './dist',
        ignore: ['node_modules', 'webpack.config.js'],
      }),
    ]
  },
  // other possible configuration options here...
};

The building commands

Here are the commands defined in my package.json . You will need to add the pushtoprod command (and maybe a deploy one too):

{
  "name": "howfast",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "NODE_ENV=production vue-cli-service build",
    "lint": "vue-cli-service lint",
    "pushtoprod": "export VUE_APP_SENTRY_RELEASE=$(git rev-parse HEAD) && yarn build && yarn deploy",
    "deploy": "gh-pages -d dist -m 'Autodeploy [skip ci]'"
  },
  ...
}

I can then type:

• yarn serve to start the development server (built-in vue-cli feature)
• yarn build to generate a production-ready build (without a Sentry release information)
• yarn deploy to deploy the bundle to GitHub Pages (static hosting for free)
• yarn pushtoprod to build the production bundle with Sentry release information, and deploy the bunde on GitHub Pages

Note that I am using the GIT commit hash ( git rev-parse HEAD) as the release ID for Sentry — this is a common pattern to keep track of releases but you can set it up to anything you need.

Results

Next time you type yarn pushtoprod , source maps will be uploaded to Sentry. You can check this in the Release Artifacts page:

From now, new errors registered by Sentry will include the detailed source code which triggered the exception:

You now have complete vision over the bugs that may stay hidden in your code. Happy debugging!

Important note: by switching productionSourceMap to true in vue.config.js , we now generate source maps for all the chunks (app + vendors) and also add them to the dist folder. Depending on your deployment pipeline, this may deploy them to your production server, which may not be desirable. Ideally, we would only generate and upload source maps for the application chunk, but this requires tweaking the Webpack configuration further and is out of scope of this post.