Source Maps – Debug your Bundled, Minified Code

While developing a web app, it’s a good idea to bundle all your various JavaScript files and libraries into a single, minified file for production. Bundling makes your app faster by reducing download size and saving the browser from having to perform multitudes of HTTP requests just to render the page.

However, bundling comes at a cost. Debugging bundled JavaScript is often a nightmare. If your app has an error, the error in the console points at the point in the bundle file where the code failed, which may or may not bear any resemblance to your actual project files.

Which would you rather debug?

Which would you rather debug?

Wouldn’t it be great if the debugger was smart enough to point you at your original, pre-bundled code instead? Enter source maps, a way to preserve reference to your original file and code structure, even through bundling.

Before We Begin

This article uses the following tools, so make sure you have them first (or at least the basic concepts about them):

(PS: Grunt and Browserify can do source maps, too.)

How Source Maps Work

A source map is a composed of data that links pieces of your minified bundle back to the original, unbuilt files. Modern dev tools will automatically follow the map for any console.log or line queries you perform.

Showing The Problem

Let’s say I have a simple console.log in an angularjs controller someplace:

  .controller('CtrlMain', function ($scope) {

When we run the app and look in Chrome’s JavaScript console, it provides a very unhelpful link to where the log was executed:
Screenshot from 2014-11-27 17:07:20Oh, it’s in the one and only line in my bundled script? I never would have guessed.

To generate bundle.js, I’m using the following task in Gulp:

gulp.task('build-js', function () {
  gulp.src([jsDir + 'module.js',jsDir + '*.js'])

This concatenates all JavaScript files into a single file called bundle.js, creates dependency injection annotations so Angular doesn’t choke on the minified code, minifies the code using gulp-uglify, and finally writes it to a build directory.

Adding Source Maps To The Build Process

Here’s how to add source map creation to this build process, using gulp-sourcemaps:

gulp.task('build-js', function () {
  gulp.src([jsDir + 'module.js',jsDir + '*.js'])

Before we do anything to the JavaScript files, we call sourcemaps.init(). This tells gulp-sourcemaps to pay attention and generate our source maps while the build process occurs. sourcemaps.write() signals that we’re done processing the .js files and ready to write out the bundled file.

IMPORTANT NOTE: All plugins used between sourcemaps.init() and sourcemaps.write() must be supported specifically by gulp-sourcemaps. You can find a list of supported plugins here.

The Final Product

Now let’s build and run the app again and see what we get:

Screenshot from 2014-11-27 18:19:39

Much better

Now the console.log behaves as if we’re working with the clear, unbuilt versions of our files. We can click that link on the left to see exactly which line contains the log. Ahhhh.


How to quit Vi (and more tips for getting started with Vi)

If you opened vi or Vim because you heard it’s what all the cool kids use, chances are your first question is “Aaaaah! How the heck do I get out of this bizarre thing?!”

Don’t panic! Press the Escape key, to make sure you’re in Command Mode. Type “:q“, without the quotation marks, and press Enter.

If you get an error message saying “No write since last change”, type “:q!” and press Enter. You should now be back in your normal command line interface.

Phew! That’s a relief, huh? Now that you’re safely out of vi, here are some reasons why you should go back in and learn how to use it.

Reasons to use Vi (or Vim)

Vi (and usually Vim) is on practically every Unix-like system in existence

Vimlogo.svgVi is specified in the POSIX standard, which means that practically any flavor of Unix or Linux will include it. Sitting down at a coworker’s computer? Vi is waiting for you. Using SSH to go into a completely foreign system with literally nothing but the OS installed? Oh, hi vi, nice to see you again!

A brief note on the difference between vi and Vim: vi was written back in 1976. Vim is a “sequel” of sorts to vi that added features like syntax highlighting, scripting, advanced regular expressions, a help system, and more. I’m using Vim, but my understanding is the basic command structure is shared by both programs.

It’s fast to use

Or it will be, once you’ve used it enough. You rarely have to take your hands off the keyboard to complete almost any text editing task you can think of. In addition, vi’s interface is optimized such that the most commonplace tasks are on the home row, and extremely quick to perform. An experienced vi user can be extraordinarily productive.

It’s what all the cool kids use

Don’t underestimate the benefits of peer pressure! Vi and Vim have a huge community of users who swear by them, some of whom have been using it for decades. Through countless iterations of hardware and software, vi has stood the test of time as the preferred text editor of programmers and sysadmins everywhere. That’s got to count for something, right?

I could go into how powerful and customizable the vi editor is, but I’m just starting my own exploration of it, and frankly, the most important thing is that you can perform basic tasks, so the editor stops feeling like an alien torture device. Deeper understanding can wait until you’re comfortable. So let’s move onto:

Vi / Vim Basics

Opening vi

To open vi, open a terminal window, type “vi“, and press Enter. To open a file with vi, type the filename afterwards, as in “vi filename.txt“. If that file does not exist in the local directory, vi will begin creating a new file with that name.

Type “i” to enter Insert Mode

Vi is a modal editor, which means that the commands you can use depend on which mode you are in. When you open vi, it defaults to the Command Mode. For people who are used to standard text editors, Insert Mode will be far more familiar. Press the “i” key to enter Insert Mode, then begin typing normally. You’ll see your text entered onto the screen.

Undo and Redo (Vim only)

When you’re starting out, it’s natural to make mistakes. To undo, first make sure you’re in Command Mode (by pressing the Escape key). Then tap the “u” key. You should see your last change undone. You can keep pressing “u” to back up through vi’s change history. To redo, press “Ctrl + r” (“r” by itself is the Replace command).


h“, “j“, “k“, and “l” in Command Mode correspond to left, down, up, and right respectively. This will seem really weird at first, but using the keys right in the home row makes it very fast to navigate.

Note that you can use the regular arrow keys as well, but you should try your best to get used to the home row keys. Train that muscle memory: it’s worth it.

For faster navigation, use “Ctrl + u” and “Ctrl + d” to half-page up and down, respectively. There are many other ways to navigate a file as well, but these will serve you well enough for now.

Saving and Quitting

Once you’ve made some changes, type “:“. You’ll now notice your cursor is at the bottom of the terminal window. Press the “w” key so that the bottom of the window says “:w“. Press Enter, and you’ll get a message that your file was saved.

As mentioned above, you can now type “:q” to quit vi. If you tried to quit without saving, you’ll get an error. You can type “:wq” to save and quit at the same time, or “:q!” to quit without saving.


Type “/” in Command Mode to open a search prompt at the bottom of the window. Then type whatever word you want to search for and press Enter. To go to the next search result, press the “n” key. To go to the previous result, press “Shift + N“.

Basic Vi Cheat Sheet

Quit without saving


Save and quit


Enter insert mode


Move left / down / up / right

h  j  k  l

Beginning of word / end of word

b  e

Move to the end of the line


Page up / page down

ctrl + u   ctrl + d

Leave insert mode


Search (must be in Command Mode)


Next Steps

You now know enough about vi to use it for simple tasks. Once you’re comfortable with the above, try typing “vimtutor” at the command line for a nice tour of some of Vim’s intermediate features.

Vi and Vim have a vast array of commands and customizable elements, far more than any blog post can hope to cover. Once I’m a little more familiar with Vim myself, I’ll post a follow-up article with some good tips.

In the meantime, here are some helpful resources on Vi: