Debugging

When contributing to the core repo, writing a loader/plugin, or even just working on a complex project, debugging tools can be central to your workflow. Whether the problem is slow performance on a large project or an unhelpful traceback, the following utilities can make figuring it out less painful.

• The stats data made available through Node and the CLI.
• Chrome DevTools via node-nightly and the latest Node.js versions.

Stats

Whether you want to sift through this data manually or use a tool to process it, the stats data can be extremely useful when debugging build issues. We won't go in depth here as there's an entire page dedicated to its contents, but know that you can use it to find the following information:

• The contents of every module.
• The modules contained within every chunk.
• Per module compilation and resolving stats.
• Build errors and warnings.
• The relationships between modules.
• And much more...

On top of that, the official analyze tool and various others will accept this data and visualize it in various ways.

DevTools

While console statements may work well in simpler scenarios, sometimes a more robust solution is needed. As most front-end developers already know, Chrome DevTools are a life saver when debugging web applications, but they don’t have to stop there. As of Node v6.3.0+, developers can use the built-in --inspect flag to debug a node program in DevTools.

This gives you the power to easily create breakpoints, debug memory usage, expose and examine objects in the console, and much more. In this short demo, we'll utilize the node-nightly package which provides access to the latest and greatest inspecting capabilities.

Let's start by installing it globally:

npm install --global node-nightly

Now, we'll need to run it once to finish the installation:

node-nightly

Now, we can simply use node-nightly along with the --inspect flag to start our build in any webpack-based project. Note that we cannot run NPM scripts, e.g. npm run build, so we'll have to specify the full node_modules path:

node-nightly --inspect ./node_modules/webpack/bin/webpack.js

Which should output something like:

Debugger listening on ws://127.0.0.1:9229/c624201a-250f-416e-a018-300bbec7be2c
For help see https://nodejs.org/en/docs/inspector

Now jump to chrome://inspect in the browser and you should see any active scripts you've inspected under the Remote Target header. Click the "inspect" link under each script to open a dedicated debugger or the Open dedicated DevTools for Node link for a session that will connect automatically. You can also check out the NiM extension, a handy Chrome plugin that will automatically open a DevTools tab every time you --inspect a script.

We recommend using the --inspect-brk flag which will break on the first statement of the script allowing you to go through the source to set breakpoints and start/stop the build as you please. Also, don't forget that you can still pass arguments to the script. For example, if you have multiple configuration files you could pass --config webpack.prod.js to specify the configuration you'd like to debug.