Debugging Webpack applications in WebStorm

Posted on September 28, 2015 by Ekaterina Prigara

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).

https://webpack.github.io/assets/logo.png

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:

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:

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.

mark_as_excluded

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

preference_exclude

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.

webpack_scripts

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

webpack_js_debug_congif

And now we’re ready to debug:

webpack_breakpoint

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.

Develop with pleasure!
– JetBrains WebStorm Team

About Ekaterina Prigara

Ekaterina Prigara is WebStorm product marketing manager at JetBrains. She's passionate about new technologies, UX and coffee.
This entry was posted in Early Access Preview, Tutorials and tagged , . Bookmark the permalink.

31 Responses to Debugging Webpack applications in WebStorm

  1. Simen Bekkhus says:
    September 30, 2015 at 6:13 am

    This is pretty sweet!

    Any thoughts on creating a plugin for webpack (e.g. WebstormWebpackPlugin) that exposes the configuration you need to know to make it work? Instead of manually setting it up. It’d also allow you to add new features without relying on the user to change their config

    Reply
    • Simen Bekkhus says:
      September 30, 2015 at 6:14 am

      Also (as I can’t edit…) any way you can resolve aliases and resolution within webpack to allow navigation to aliases during import et.al.?

      Reply
    • Ekaterina Prigara says:
      September 30, 2015 at 9:19 am

      We have some ideas on a plugin that would help to resolve the paths and aliases based on a runtime data (no way we can do that based on static code analysis), but unfortunately we won’t be able to implement it on time for WebStorm 11 release…

      Reply
  2. Alan Gabriel Bem says:
    October 5, 2015 at 4:15 am

    Can you provide tutorial for setting up such debugging with remote server (e.g. where server root points directly to build directory) and source maps are generated with other tools (in my case it’s browserify)?

    Reply
  3. Paul says:
    October 5, 2015 at 11:28 pm

    Thanks for the tutorial.

    Just wondering how I get to the screen after this line:
    “We need to map our application root to webpack:///.”

    I can’t work out how to map the application root.

    Thanks

    Reply
    • Ekaterina Prigara says:
      October 7, 2015 at 8:37 am

      That’s the screen of JavaScript debug configuration. You can create run configuration from the menu Run – Edit configurations…

      Reply
  4. Peter Sulatycke says:
    October 10, 2015 at 4:29 pm

    How about source maps with webpack bundles for unit testing with Karma?
    This is where source maps are really useful – testing.

    Reply
  5. Michiel says:
    November 9, 2015 at 4:28 pm

    Thanks for the tutorial. However, I don’t manage to get it set up all the way.
    If I look in the Scripts-tab in Webstorm (OSX), I see webpack://, but under that there’s no ‘.’ folder, but the full path to Users/me/Projects/MyProject.
    I can right click that to map it, and the entry appears in the debug configuration. I refreshed my browser, the debug connection and recompiled js and maps via Webpack. (My maps work fine in the Chrome debugger) But still the red debug dots stay plain when I click them, without a checkmark. So no breakpoints yet. Am I missing something?

    Reply
  6. Jonas Kello says:
    November 16, 2015 at 3:45 pm

    Is there some way to get debugging in Webstorm to work together with webpack hot realoading? It requires that we can use a web-serer with middleware, like express, but I think Webstorm insists on using it’s own webserver to debug?

    https://www.npmjs.com/package/webpack-hot-middleware

    Reply
  7. Jesse Schalken says:
    November 23, 2015 at 6:41 am

    It should be noted that if you have a node_modules/ folder it needs to be mapped to webpack:///./~

    Reply
  8. bahgat says:
    January 6, 2016 at 9:05 pm

    it work fine,

    could you give use a simple example with nodejs , the debugging not debug the sourcemap but the bundle file

    thanks in advance

    Reply
  9. EvynXu says:
    January 28, 2016 at 1:24 am

    Why not use Reactjs breakpoint debugging, using a simple js debugging is no problem.

    Reply
  10. Samuel says:
    February 2, 2016 at 12:21 pm

    I’m just wondering here, Do I need to build my entire project always that I need to debug? Can’t I debug in dev mode with debug enabled? Because just running with debug enabled without build the entire project I don’t have the build folder.

    Could you help me?

    Reply
  11. matt says:
    March 5, 2016 at 1:44 am

    I’m having a problem at this step “The next step requires us to map the URL that specifies the paths to local files in the source map. ” Is this process covered in one of your video tutorials?

    Reply
  12. Rich Brown says:
    March 17, 2016 at 1:22 am

    I have it working reliably. I got instructions through https://youtrack.jetbrains.com/issue/WEB-20781 (Thanks, Ekaterina!)

    I also decided to summarize the steps on my blog at: http://richb-hanover.com/debugging-webpack-apps-with-webstorm-2016-1/

    Reply
  13. Cedric says:
    March 18, 2016 at 1:08 pm

    Is there a possibility to get this work with typescript source, so I can set the breakpoints in my typescript files?

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *