Why we need to create source maps
What are minification and asset combining?
But why do I need source maps?
What things will I need to set this up?
Here is a list of things you should have ready to set up to implement source maps with your application:
- The ability to install the UglifyJS2 NPM package on your local machine or production environment.
Setting up source maps with Rails 4/5
Note: while Sprockets 4 is rumored to support source maps fully, version 3 (currently used by Rails 4/5) does not.
Step 1: Download UglifyJS2
npm install uglify-js -g
This will install UglifyJS2 from NPM globally on your machine (usually preferable).
Step 2: Prevent Sprockets from grabbing other files
Next we need to make some changes to our Rails application’s default behavior.
Here we’ll remove the line that says //= require_tree .
//= require jquery
//= require jquery.turbolinks
//= require jquery_ujs
//= require turbolinks
//= require bootstrap/dropdown
//= require_tree .
Many Rails experts recommend using this manual precompile process for production environment usage to have the assets loaded and ready to go from the start. In most Rails development environments the assets are recompiled each time they are requested or changed. While this works great for troubleshooting and visualizing the changes, it is a slow process especially for larger file sizes and for large numbers of files. Precompiling the assets for the production environment relies on the idea that the assets should not change often in production if they were properly tested and set up during development.
Note: the rake assets:precompile command will also do the same with your CSS/SCSS files and create a new minified/combined version. For the purposes of this post we’ll ignore these other files.
Step 4: Use the UglifyJS2 command
Next we’re going to use the uglifyjs2 command. The basic syntax we’re looking to work with is as follows:
Breaking this down:
--source-maps public/assets/mymin.js.map -> this tells the uglifyjs command that we want to create a source map for these files named mymins.js.map and store it in the public/assets/ directory of your application.
-o public/assets/mymin.min.js -> Tells the uglifyjs command which directory and file you want the new minified/combined version of the source files to be located.
Note: Naming this file with the .min.js notation will help identify that it is the minified version for ease of use and tracking later. For more information on additional UglifyJS2 commands and options check out the official UglifyJS2 documentation.
So we have our minified/combined files and our source map. One of the major benefits of usign Raygun in this way is that you don’t have to setup/create your own error tracking for both your Rails and JS app. Then you can view both apps in one location. You’ll need your Ruby on Rails application connected to Raygun before you start. (You can take a free 14 day trial here – it doesn’t take a moment to get set up.)
Step 1: Set up a separate application in Raygun
- Once you are logged into Raygun, click on the ‘+’ symbol in the upper left corner of your browser window:
- Click on ‘Create Crash Reporting application:’
- Enter in a name for your application and then click the ‘Next’ button:
<%= csrf_meta_tags %>
<% flash.each do |key, value| %>
<div class="alert alert-<%= key %>">
<%= value %>
<% end %>
rg4js('apiKey', YOUR_API_KEY_GOES_HERE );
Step 2: Upload your file
Validate the source map you created earlier by uploading the file to your Source Map Validator. If the source map is valid you should see the following:
Step 3: Head to the ‘source map center’
Go back to your Raygun Crash Reporting dashboard and click on ‘JS source map center‘ under ‘Application settings‘ in the left side navigation menu:
Option A – Upload via page
Either drag and drop a file into the dialog window or click on ‘or select a file’ to open a file explorer window:
Option B – Upload via API endpoint
Note: Additional information regarding how to upload source maps and related files via the API endpoint are location in our Source Maps documentation.
Share you feedback and suggestions on source maps in the comments below…