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

Update: Starting with WebStorm 2016.1 you don’t have to configure path mappings in the Debug configurations for most of the apps, just make sure that you have devtool: "source-map" in your webpack.conf.js. However, that might still be required for some complex Webpack configurations.

Update 2: WebStorm 2017.1 brings further improvements to debugging the apps with Webpack. Ensure that the source maps are enabled, specify the URL your app is running on in the debug configuration and you’re ready to go.

Check out our tutorials on debugging React apps created with Create React App and Angular apps created with Angular CLI.

 

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 might be 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 Tutorials and tagged , . Bookmark the permalink.

83 Responses to Debugging Webpack applications in WebStorm

  1. Simen Bekkhus says:

    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

    • Simen Bekkhus says:

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

    • Ekaterina Prigara says:

      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…

      • David Ford says:

        Yes. This would be a great feature. If the IDE does not know about your other js files its no better than a text editor.

  2. Alan Gabriel Bem says:

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

  3. Paul says:

    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

    • Ekaterina Prigara says:

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

  4. Peter Sulatycke says:

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

  5. Michiel says:

    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?

  6. Jonas Kello says:

    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

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

  8. bahgat says:

    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

    • +1 for nodejs

      The step where I could add path mappings, I can’t for node, because it’s not for the browser, therefore I can’t use the JavaScript Debug configuration

      • Ekaterina Prigara says:

        Unfortunately, at the moment you can’t debug Node.js app built with Webpack, I’lve reported an issue: https://youtrack.jetbrains.com/issue/WEB-19984
        Please follow it for the updates.

        • Yoav Aharoni says:

          I managed to debug wepack nodejs app in WebStorm using this webpack config:

          js
          ...
          // devtool: 'source-map',
          plugins: [
          new webpack.SourceMapDevToolPlugin({
          filename: '[name].js.map',
          sourceRoot: '/',
          noSources: true,
          moduleFilenameTemplate: '[absolute-resource-path]',
          fallbackModuleFilenameTemplate: '[absolute-resource-path]',
          }),
          ],
          ...

          Hope this helps

  9. EvynXu says:

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

  10. Samuel says:

    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?

  11. matt says:

    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?

  12. Rich Brown says:

    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/

  13. Cedric says:

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

    • Ekaterina Prigara says:

      Are you using the TypeScript compiler directly or it’s wrapped in Webpack? Should work file with the source maps generated by TypeScript compiler. If not, please share a bit more details about your configuration.

      • Cedric says:

        I’m using the ts compiler directly, this is what’s in my tsconfig file:
        {
        “compilerOptions”: {
        “module”: “commonjs”,
        “target”: “es5”,
        “sourceMap”: true
        },
        “exclude”: [
        “node_modules”
        ]
        }
        and this is my webpack.config.js:
        module.exports={
        entry: “./Index.js”,
        devtool: “source-map”,
        output: {
        path: __dirname + “/dist”,
        filename: “bundle.js”
        }
        }
        Maybe you can tell me whats wrong

  14. Idan perkal says:

    I have followed your tutorial and I just can’t see the webpack:/// in the script tab in the debugger tool Windows. What’ll am I missing?

  15. Nikolay Kupstas says:

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

  16. Robb E Lovell says:

    How can I setup webstorm so that I can set breakpoints in coffeescript when using webpack?

  17. jacks says:

    This tutorial has super naive and simple project. Instructions does not seem to apply in any more complex projects than this. For example, i don’t have any web pack urls, but vm:123 kind of notes on the place instead. Could you provide some more complicated examples pls?

  18. Frank Arnold says:

    Remote debugging with Electron/Webpack/React is unfortunately no working?

    IMO the Chromium remote setting needs the same mapping from the bundled file to the original files? Is there also a problem with JSX because React can use JSX files to allow writing of HTML like code inside Javascript.

    I have no idea if this needs only a different configuration or if debugging of Electron/Webpack in combination with React is not working because Web/PHPStorm don’t support this?

    • Ekaterina Prigara says:

      You still need to compile your JSX code to JavaScript so that it can be executed by Electron. As long as you have generated source maps, debugging should work fine. Please let us know, if it doesn’t work for your project (either on our issue tracker: https://youtrack.jetbrains.com/issues/WEB or our tech support: https://www.jetbrains.com/support/). Thank you!
      In WebStorm 2016.2 we’ve improved support for Webpack and in most cases now you don’t need to configure mappings in the debug configuration.

      • Frank Arnold says:

        Debugging is working now if I setup remote chrome debugging so I can debug the render process.
        But the mapping to the original jsx files is not working. The debugger is walking thru the bundle.js (the bundled scripts from Webpack. I’ve tried also inline maps with Webpack but this doesn’t change something..

        I expected that PhpStorm will find the “bundle.js.map” and use them to debug inside the jsx files and not the bundle.

        Btw. Webstorm 2016.2 means that is also updated int the actual PHPStorm 2016 2.1 ?

        Because it’s not working as expected I debug this time directly with the chrome developer tools. There this mapping works perfectly.

        • Ekaterina Prigara says:

          Yes, debuggers should work the same in WebStorm and PhpStorm 2016.2.

          Can you please share a sample project with us? That would help to see why it doesn’t work. Thanks!

          • Frank Arnold says:

            I can only say that debugging stops directly in the zlib.js file (where Webpack seems to bundle some code)… I can see the code and debug it but this is not how it should work.
            For some reason this mapping to the source file is not working.

            In the scripts view of the debugger in PHPStorm I see the jsx and in brackets behind every jsx file “(file:///… bundle.js”)
            Webpack was set to create inline source maps (devtool: “inline-source-map”

            All is set correctly and also the node.js debugging of the main process is working. The render processing debug is working too (chrome debug) but the mapping to show the jsx files is not working.

  19. Chris Malloy says:

    Breakpoints are working, and I am getting any console.log statements showing up in the WebStorm console.

    I am not getting any errors showing up in the WebStorm console, and right clicking in the browser and clicking “Inspect in WebStorm” does nothing.

  20. Michael Burgess says:

    Can you let me know how to make this work if I’m also using React with a routing engine.

    For example, I may have index.html as my single page, but in the browser I just navigate to the /home URL, not index.html.

    How can I make WebStorm start a debugger, but accept routes in the URL rather than the page URL? Also, how can I set the default route to navigate to?

    Thanks!

    • Ekaterina Prigara says:

      Dear Michael, I haven’t tested debugging React apps with routing, but from the general knowledge I’d would say that that should not affect debugging in any way. You just need to specify the URL for the page you start your debugging with, e.g. localhost:3000. The debugging session won’t end if you go to localhost:3000/home. Does that answer your question?

      • Michael Burgess says:

        Hi Ekaterina – only just got round to looking at this sorry. I cannot get this to work in WebStorm. I have cloned your above simple example and that works fine, as you are not using any kind of routing, simply loading the html page.

        I need to set up WebStorm so that if I Run or Debug my project, it loads index.html, but instead of putting index.html in the URL, puts /home.

        If it puts index.html in the URL it will not work, as the routing engine will try to match “index.html” against its known routes and cannot match to it.

        I’ve trivialising my example here, as unfortunately I cannot share what I’m, actually doing.

        Would it help if I put a basic example together on GitHub and perhaps you could clone it and tell me how to get it working?

        Thanks,
        Michael.

        • Ekaterina Prigara says:

          Please specify the URL that your app is running on in the run/debug configuration. If it’s in your case localhost:/home, then you should specify this URL. That is not required anyhow that it ends with index.html.
          Hope it helps.

          • Michael Burgess says:

            I’ve put together a basic example below – I’d like to be able to run this, using the WebStorm debugger – there’s no server-side component here in this example, just a really basic React/react-router app that renders “Hello World!” into the browser if you go to the /home route.

            Any ideas how I can Run/Debug this using the WebStorm debugger?

            Thanks.

        • Michael Burgess says:

          Here’s a really basic example – instructions in the README: https://github.com/MichaelBurgess/debugging-webpack-react-router

          • Ekaterina Prigara says:

            Thanks for your example. WebStorm built-in server can’t serve index.html file on the root address. You still need a server that would match index.html to /.
            You can use a simple Express server like here: https://github.com/ReactTraining/react-router/blob/master/examples/server.js

          • Michael Burgess says:

            Thanks for the confirmation Ekaterina. Are there examples, or steps on how I can configure a WebStorm Run/Debug configuration that would start the Express server and then launch the browser at that URL? (say http://localhost:8080/home)

          • Ekaterina Prigara says:

            You can start the server from the terminal or with a Node.js run configuration (specify path to Node.js and path to the JavaScript file that runs the server). Once the app is running, you have to specify that URL (e.g. localhost:8000/home) in the JavaScript run/debug configuration in the URL field.

          • Michael Burgess says:

            Hi Ekaterina – I’ve got this working now, but with a few minor issues, was wondering if you can help.

            I’m using webpack-dev-server to webpack bundle my JS and serve it up. If I start the dev server and then set up my run/debug config to connect to it, it does – so far so good.

            I don’t want to have to manually start the dev server myself, so I’ve added an npm target “start”, which simply calls “webpack-dev-server”. I’ve added this as a “Before Launch” NPM task.

            So:

            1) If I “Run” this, it starts the NPM start command and immediately launches my browser. Ideally I’d like it to wait for the NPM start to finish before launching the browser – is that possible?
            2) If I “Debug” this, it start the NPM start command, but never launches the browser. I then have to manually go to my URL in a browser, but because I’ve done that manually, the debugger isn’t attached to the browser

            The only way I can get debug to work, is to remove the Before Launch task and manually NPM start, then go to “Debug”. Even then, after the browser launches it doesn’t properly attach, so I need to F5 the page for it to re-attach and only then will my breakpoints work.

            So with fiddling it does work, but it’s not the smoothest experience, so I was wondering if you could help? Thanks.

          • Ekaterina Prigara says:

            Sorry, I’m not sure I understand where do you add a before launch task – to the JavaScript debug configuration? I’m not sure you really need to restart the dev server every time you start a debug session, so I would recommend to start the server manually with by double-clicking on the start task in the npm tool window once you opened your project.
            There’s no way a run/debug configuration can check that some specific npm task has finished – not all talks (and webpack-dev-server is among them) end up with an exit code.
            There’re some known limitations: if your app is running on not on a built-in server, you can’t stop on breakpoints put in the code executed on the page load (before the page loaded) on a first run (you can only in code executed afterwards, e.g. event handlers). The reason is that the IDE needs to get the source maps from the browsers to be able to stop on a breakpoint you put in an original source. That only happens once the page is loaded or reloaded.

  21. Martin Ellermeier says:

    I had a hard time to get this running for the Angular 2 webpack setup (https://angular.io/docs/ts/latest/guide/webpack.html). So it maybe helpful for somebody to mention this here.

    For this setup I need to set the first path to “webpack:///.” like in the example. The build directory in this case is “dist” and the port 8080. To get this running I need to map this directory to “http://localhost:8080”. Unfortunately this isn’t working without modification of the web pack configuration.

    In the webpack config I need to switch from the switch “devtool” from “cheap-module-eval-source-map” to “source-map”. More important to get this running is to add “contentBase: ‘./dist'” in the section “devServer”. All changed needs to be done in the “webpack.dev.js”.

    So long story short: If the debugger is not starting keep also an eye on webpack configuration.

    If someone what to test it: Here is link to git repo: https://github.com/mneller/webpack-start

  22. Roman Bronowski says:

    Webstorm 2016.3 generates REACT project using yarn and there is no webpack.config.js file or other yarn config file in which I can add “devtool: “source-map” for debugging.

    • Ekaterina Prigara says:

      All the comments in this blog require moderation, that’s why you haven’t seen your comment.

      WebStorm generated React project using create-react-app which “hides” all the configuration inside. Please see this section of their documentation about changing the default project configuration.

      • Roman Bronowski says:

        Thanks for reply. Webpack config files that I found later were added by my try to eject (yarn run eject). Although it wrote at the end that it finished with an error, all new files were added.

    • Roman Bronowski says:

      Dear Ekaterina,
      Excuse me very much. Of course there is a webpack.config.dev.js in ./config folder. Please cancel my all today comments.
      Sorry for all that. I do not know why I was so blind. I have just changed my choice from Angular 2 to REACT.
      Good luck. Your Webstorm is the best in the world.

  23. Roman Bronowski says:

    Why my previous comment about a problem with debugging generated REACT projects was canceled?
    Is there a possibility to debug such a project although I cannot change the option “devtool” as there is no editable webpack.config.js file?

    • Roman Bronowski says:

      Sorry, you can canceled this second comment because maybe a browser showed me your page from the cache and without my comment.
      Sorry for that but I urgently seek a possibility for debugging such a project.

  24. Stefan Dausend-Werner says:

    Debugging works fine out of the box using Webstorm 2017.1 and loading modules via the require syntax. Yet using ES6 import statements, webpack will pack the imported variables into an object of the form of __WEBPACK_IMPORTED_MODULE_n_fileName__ ={a:…, b:…, c:…}. This object is displayed in the debugger but extremely difficult to use for debugging purposes. Is there a recommended solution to get a useful mapping for those objects or a webpack based solution?

    Cheers and Thanks

  25. James says:

    Anyone having issues when debugging a site using https instead of http? My webpack source maps work fine only with http. When debugging an https site, in the Chrome devtools I can see the webpack:// source maps, but in the WebStorm “Scripts” debugging tab, they are absent. None of the break points are hit either. Setting mappings under run configurations doesn’t help.

  26. David Moshal says:

    Hi, wondering if it’s possible to debug typescript with webpack as above?

  27. Bert Vandamme says:

    Hi,

    I’m having trouble debugging javascript unit tests in Intellij IDEA 2017.1.2.
    The karma configuration is wired up with the webpack config and sourcemaps are generated with devtool: ‘source-map’.
    Running a karma run config runs all tests without an issue, but debugging the same run config does end up in any breakpoints being hit.

    Any pointers on getting this to work? Or am I going about this the wrong way?

    Relevant project dependencies include:

    – webpack 2.2.0
    – karma 1.3.0
    – jasmine 2.5.2
    – angular 1.6.2
    – angular-mocks 1.6.2

    Thanks in advance

    • Bert Vandamme says:

      Forgot to mention that debugging the application itself works out of the box as mentioned by Ekaterina’s update 2.

    • Ekaterina Prigara says:

      Hi Bert,
      Any chance you can share your project with us? Or may be you know any projects/tutorials with the similar configuration that we can try? You can contact our tech support directly.
      So far, I can’t find any known related issues on our tracker.

      • Bert Vandamme says:

        Hey Ekaterina,

        I’ll set up an example project with the same configuration and provide it to tech support.

        Thx!

        • Bert Vandamme says:

          Hi Ekaterina,

          In case you’d like to follow up:

          I’ve submitted an example project with tech support (request #973592)

          Bert

Leave a Reply

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