Recently I was faced with a bunch of front end errors occurring only in the production environment. The error reports were coming from Sentry and it was really hard to understand exactly where in the application the error was occurring. I knew I needed to see the code in order to understand what was going on.
The site was generated using a
nuxt generate Nuxt.js command, which caused another, less severe, problem. Each error was treated as unique by Sentry, since they were coming from files with different names (based on hash).
Here’s what I saw in Sentry:
Source maps can be used to retrieve the source code when displaying error messages.
What is a source map?
Source maps are for transpiled languages, what debugging symbols are for compiled languages. They contain the mapping between original human readable source code and the generated browser optimized code.
In terms of implementation, source maps are simple JSON files with
Problem with distributing source maps
The easiest way to use source maps is to deploy them on the server together with the application itself. This way, web browsers, DevTools Debugger, and Sentry will be able to easily find them.
It works great when developing and testing the application in a private environment, but unfortunately there’s a problem. In a public production environment the source code will be available to anyone visiting the site. If you want to hide the source code, you must avoid distributing source map files with it.
Sentry releases to the rescue
When we combine these two things, Sentry is able to map a production issue to the source code and display it, even though it’s not available for your web application visitors.
Sentry module for NuxtJS. Contribute to nuxt-community/sentry-module development by creating an account on GitHub.
To get this working, there are a couple of required steps:
1. Configure Sentry CLI
I’ve created the following
.sentryclirc configuration file in the root project directory:
org = <your-sentry-organisation-name>
project = <your-sentry-project-name>
I also need to specify the Sentry
auth token. I can add it to the above file, but for security reasons it’s better to pass it through an environment variable:
2. Configure Nuxt.js sentry module
I add the following section to
nuxt.config.js file to tell the Sentry module to publish the release:
By default the last commit hash will be used as release identifier during upload and at runtime, which is the best option in continuous delivery environments. However, you can also customize a release identifier as follows (make sure you use sentry-module 3.0.0 or later):
Please also note that you can use environment variables to dynamically specify Sentry module options without touching the config file. For example, setting
SENTRY_PUBLISH_RELEASE=true will enable the release upload.
3. Update the build script
I need to delete the
.map.js files before uploading the site to the server, otherwise they will be published together with the website. Sentry CLI doesn’t have such an option yet, so I need to do it manually. I use a cross-platform rimraf utility for the job, by adding the following to my
"generate": "nuxt generate",
"dist": "npm run generate && rimraf dist/**/*.js.map"
Finally, I add the required library to my
npm install --only=dev rimraf
Now I have the original source code beautifully displayed on the Sentry issue page, along with the correct source file name:
I hope this was useful — please do not hesitate to share your thoughts.
- I clarified the release identifier handling and simplified the solution by using
sentry-cli releases propose-version.
- I simplified release identifier handling even further thanks to improvements in Sentry module 3.0.0. Mentioned environment variables to specify options.
- Releases in Sentry: https://docs.sentry.io/workflow/releases
- Nuxt Sentry community module: https://github.com/nuxt-community/sentry-module
- Sentry official command line utility: https://github.com/getsentry/sentry-cli
- Sentry official Webpack plugin: https://github.com/getsentry/sentry-webpack-plugin