Debugging Webpack applications in WebStorm

Webpack is a module bundler. It allows you to build your modular application similarly to the way it is done with a combination of tools like Browserify and Gulp or Grunt.

In this blog post we actually won’t dive into how to get started with Webpack, as lots of great tutorials are available in the Webpack documentation. Instead we’d like to focus on debugging applications built with Webpack in WebStorm 11 EAP (that you can learn more about here).

Here’s our very simple app: it’s available on Github and is already fully configured.

We have a simple Webpack configuration file that describes how files in our app are compiled and bundled. To keep it simple we won’t use any additional Webpack loaders. Webpack would bundle all our JavaScript assets in a single file that we can use in our app:

module.exports = {
   entry: "./entry.js",
   output: {
       path: __dirname + "/build",
       filename: "bundle.js"
   }
};

Now let’s see how we can debug our app.

Usually we just put the breakpoints in our files and hit debug. But here we have all files bundled by Webpack in one. How can WebStorm match our original files to the code that is actually executed? Source maps help us with that: they provide information about the source files built. To generate source maps with Webpack you need to add option to your configuration file:

devtool: "source-map"

But there are still a couple of things that WebStorm needs to do:

• it needs to locate the directory with the Webpack output files (including source maps); and
• it needs to understand the paths to the source files specified in the source map and match them to their location in the project.

Doing any kind of “black magic” to guess these paths can actually slow down the start of the debug session and may work unpredictably on complex projects. Instead we recommend specifying the mappings in the JavaScript debug configuration:

• from the remote URL of the compiled script to its location in the project;
• from the URL of source (listed in a source map) to the local path in the project.

Configuring mappings is always required for debugging Webpack applications. When using other build tools you might also follow these steps, for example when you are using source maps and want to put breakpoints in events on page load.

So let’s go back to our example. First, let’s exclude build directory from the project. That way the IDE will preload the source maps from it, moreover, it won’t index these files on every build or won’t suggest you to navigate to them from your source files.

Right-click on the directory in the Project view and select Mark Directory As and then select Excluded.

Or, go to Preferences | Project | Directories and exclude the directory from the project there:

We run the application on the WebStorm built-in web server that uses the following structure of the URL: http://localhost:/ and then the path to the file from the project root. The post number can be changed in Preferences | Build, Execution, Deployment | Debugger.

So we can just map our local build directory to http://localhost:63342/debugging-webpack/build – the file paths from the project root match.

The next step requires us to map the URL that specifies the paths to local files in the source map. If we go to the Scripts tab in our Debugger tool window, we’ll notice webpack:///. folder – that’s actually a URL Webpack uses in its source map for the paths to the original files.

We need to map our application root to webpack:///.

And now we’re ready to debug:

You may be wondering why all this can’t be done automatically. One reason is that at the moment WebStorm cannot detect whether you’re using Webpack or not and how exactly it’s configured. The main reason though is that, with the flexibility that you can have with such powerful tools like Webpack and more complex application structure, the mappings can get much more complicated. So we believe that a more configurable solution is better.