Unambiguous Webpack config with Typescript

Devon Marisa Zuegel
Jun 18, 2017 · 12 min read

  • Easy to accidentally use old syntax — Webpack’s authors have taken pains to ensure backwards compatibility. This is nice of them, because it allows developers to be confident that Webpack won’t break underneath you (and this would be a disaster if it did, because it is the build tool of choice for an increasing portion of the internet). Plus, it doesn’t put any constraints on people’s designs or preferences. But this lack of constraints is also a nightmare, because it’s way too easy to use outdated APIs. New projects should use Webpack 2, but it’s nearly impossible to differentiate between them when viewing examples online. The two versions share a lot of naming conventions, and they don’t enforce usage consistency. As a result, most people are using a mix of Webpack 1 and 2 without knowing it.
  • Lack of sensible defaults — Webpack’s customizability is powerful, but it also leaves the newbie (or even someone who just wants to whip up something quickly) out in the cold. The interface does not guide you to reasonable defaults; it requires upfront knowledge of the underlying tool before you can even get started.

Typescript to the rescue

Around the time I started using Webpack, a friend introduced me to Typescript, and I’ve since used it in all of my side projects. I won’t gush about it here — I’ll let the Typescript core team do that — but I will say that it’s transformed the way I build software. Within weeks, I replaced every line of Javascript with strict Typescript. The only exception was my Webpack config files, because the tool did not support TS, as far as I could tell from documentation. I thought I’d have to manually compile the config into JS files before every compilation, which would be slow and a whole other source of frustration around Webpack.

  1. Replace your config’s extension from .js to .ts.
  2. Run webpack — config webpack.config.ts as usual.

Discovery with types

You can do more, but even with these two tiny changes you’ll immediately see benefits. (I’ll get into extensions later.) In particular, the type definitions for Webpack are fantastic, and you get these for free. Typescript’s Autocomplete and type guards guide you to the right usage, without the friction of a Google search or guessing how what something is called. Rather than googling for overloaded terms like “resolve” or “module”, which will turn up many irrelevant or outdated results, you can see the options exposed by the interface in your text editor. And if you want visibility into what’s going on under the covers, Go To Definition jumps you right to the location in the .d.ts file.

{ "keys": ["ctrl+d"], "command": "typescript_go_to_definition" }
  • oneOf is “an array of Rules from which only the first matching Rule is used when the [parent] Rule matches”
Even if we were doing something more complex, we might still prefer to keep our rules defined at the top level. For instance, the oneOf example is equivalent to the following snippet, which is more explicit, more concise, and easier to understand:
  1. Constrain the Module interface to just the Webpack 2 features.
  2. Constrain the rule interface to NewUseRule.
  3. Write the rule to pipe .css files through the style-loader.

Documentation in your text editor

Not only are the Webpack type definitions thorough, but the maintainers have added extensive comments to everything. If you’ve ever wondered what the impact of changing your devtool option would be, you’ll see a nice comment like this above that line in the definition along with all of the possible values:

Constraining the interface to what you need

To get the full benefits of writing your config in Webpack, you’ll want to add a few more things. One addition is you can add return types to various components of the config. For instance, I like adding the webpack.Configuration type to partials, because it ensures that they can the be webpackMerged in the top-level config file.


The official Medium publication for the webpack open source project!

Devon Marisa Zuegel

Written by

Blog moved to: devonzuegel.com • Twitter: twitter.com/devonzuegel



The official Medium publication for the webpack open source project!