Webpack block for the webpack 2.x base configuration.

npm install @webpack-blocks/webpack


webpack-blocks - webpack base configuration

Gitter chat NPM Version

This is the webpack block providing webpack core functionality. Also provides all @webpack-blocks/core exports for convenience.


const HtmlWebpackPlugin = require('html-webpack-plugin')
const {
} = require('@webpack-blocks/webpack')
const { css } = require('@webpack-blocks/assets')

module.exports = createConfig([
  setMode(process.env.NODE_ENV || 'development'),
    new HtmlWebpackPlugin({
      inject: true,
      template: './index.html'
  env('development', [
    // will only enable source maps if `NODE_ENV === 'development'`


createConfig(configSetter: Function[]): object

Takes an array of config setters (the functions returned by invoked webpack blocks), invokes them and returns the resulting webpack config object.


group(configSetters: Function[]): Function

Combines an array of blocks to a new joined block. Running this single block has the same effect as running all source blocks.

env(envName: string, configSetters: Function[]): Function

Applies an array of webpack blocks only if process.env.NODE_ENV matches the given envName. If no NODE_ENV is set, it will be treated as 'development'.

Use like this:

module.exports = createConfig([
  env('production', [extractText()])

match(test: string|RegExp|Array, options: ?object, configSetters: Function[]): Function

State on which files to apply the loader blocks passed in this call. Works like group(), but adds the file matching information to the context that can be used by the child blocks. The options parameter is optional.

Use like this:

module.exports = createConfig([
  match(['*.scss', '!*node_modules*'], [

To match multiple file patterns you can pass a pattern array:

module.exports = createConfig([
  match(['*.sass', '*.scss'], [
    /* blocks */

when(condition: boolean, configSetters: Function[]): Function

Applies an array of webpack blocks only if condition is true (or truthy).

Use like this:

module.exports = createConfig([
  when(process.env.CI, [reportBuildStatsPlugin()])

Shorthand setters

addPlugins(plugins: WebpackPlugin[])

Add custom plugins to the webpack configuration.

Example usage:

addPlugins([new HtmlWebpackPlugin()])

customConfig(webpackConfigSnippet: object)

Add some custom configuration to the webpack configuration. The object you pass will be merged into the webpack configuration object.

defineConstants(constants: object): Function

Replaces constants in your source code with a value (process.env.NODE_ENV for example) using the webpack.DefinePlugin. Pass an object containing your constant definitions: { [constantName: string]: <constantValue: any> }.

Every constant's value is JSON.stringify()-ed first, so you don't have to remember.

Using defineConstants multiple times results in a single DefinePlugin instance configured to do all the replacements.

setEnv(constants: string[]|object): Function

Replaces constants in your source code with a values from process.env using the webpack.EnvironmentPlugin.

Using setEnv multiple times results in a single EnvironmentPlugin instance configured to do all the replacements.

module.exports = createConfig([
    BABEL_ENV: 'development', // use 'development' unless process.env.BABEL_ENV is defined
    PORT: 3000

entryPoint(entryPoint: string|string[]|object)

Adds one or multiple entry points. If the parameter is not an object the entry point(s) will be added to the default chunk named main. This way we make sure that the resulting https://webpack.github.io/docs/configuration.html#entry configuration property will always be an object.

optimization(optimizationOptions: object)

Set the optimization settings.

performance(perfBudgetOptions: object)

Set a performance budget. Performance budgets are custom limits (like max bundle size) you can set to make webpack warn you or throw an error if the application exceeds those limits.

Options object:

  maxAssetSize: number,         // File size limit in bytes
  maxEntrypointSize: number,    // Total size (of an entry point) limit in bytes
  hints: string                 // "warning" or "error"

resolve(config: object)

Sets resolve. Use it to manually override module resolution.


  // resolve `import 'Utilities'` to correct path
  alias: { Utilities: path.resolve(__dirname, 'src/utilities/') },
  extensions: ['.js', '.json'],
  modules: [path.resolve(__dirname, 'src'), 'node_modules']

setContext(path: string)

Sets the webpack context. Not to be confused with the webpack-block's context object.

setDevTool(devtool: string)

Use it to manually set the webpack devtool property, like 'eval', 'source-map' and such.

setMode(mode: string)

Sets the webpack mode.

setOutput(output: string|object)

Sets the webpack output property. Use it to tell webpack where to save the output bundle(s).

You can either pass an object that complies to the format described in the webpack docs or just pass the destination file path.

Instead of passing the destination file path you can also

  • Just pass a filename (not the complete path): The directory will default to ./build/.
  • Just pass the path to a directory (trailing /): The filename will default to bundle.js.

sourceMaps(devtool: ?string)

Just a convenience wrapper to enable sourcemaps in an easier-to-read fashion than setDevTool(). Will set webpack's devtool to 'cheap-module-eval-source-map' if no explicit devtool is passed as parameter.


Check out the

👉 Main documentation

Released under the terms of the MIT license.

Release Notes

By Andy Wermke • Published on April 27, 2020

Just a small maintenance release bumping dependencies. Thanks a lot, @marcofugaro! 😊

Attention: Minimum node.js version is hereby raised from node 8 to node 10.

By Andy Wermke • Published on March 29, 2018

📦 Version 1.0 - finally!

Here we go, version 1.0. A lot has happened and I think I speak for all of us when I say we could easily have made two major version bumps out of that one 😉

Changes since v1.0 release candidate

Support negations in match() glob patterns (#253)

You can now have exclusion patterns without writing ugly regular expressions!

match(['*.js', '*.jsx', '!node_modules'], [

Allow passing arbitrary rule options via match() (#250)

There was an undocumented limitation before when passing custom webpack rule options via match(): You could only pass include and exclude. This has been fixed now.

You can now pass any kind of option if necessary (note the enforce: 'pre'):

match('*.{js,jsx}', { exclude: 'node_modules', enforce: 'pre' }, [

Added when() (#243)

There is a new helper on the block: when(). It's a pinch of syntactic sugar for conditionals, so your config won't be cluttered with ternary operators.

module.exports = createConfig([
  when(process.env.CI, [reportBuildStatsPlugin()])

New block eslint (#254)

There is now an eslint block and it's even part of the core packages.

const { createConfig } = require('@webpack-blocks/webpack')
const eslint = require('@webpack-blocks/eslint')

module.exports = createConfig([
  eslint(/* eslint options */)

Removed proxy() from dev-server block (#251)

We trimmed down the dev-server block a little more. But don't worry, it's still easy as cake to set up a proxy server using the dev-server block:

module.exports = createConfig([
  // use only if `NODE_ENV === 'development'`:
  env('development', [
      proxy: {
        '/api': { target: 'http://localhost:3000' },

Changes since v1.0 beta

Have a look at the v1.0.0-rc release notes.

Changes since v0.4

Have a look at the v1.0.0-beta release notes and read the migration guide.

This is it. A big shout out to the contributors!

Especially @vlad-zhukov, @marcofugaro, @boxfoot, @dmitmel and @sapegin this time 😊

By Andy Wermke • Published on October 2, 2017

After months of work the v1.0 release candidate has landed!


The release candidate version is published to npm using the latest tag, not the beta tag anymore and lives now on the master branch were it belongs.

Install today using

npm install --save-dev webpack webpack-blocks

Check out our migration guide to update from v0.4!

A huge thanks to all contributors: @sapegin, @jvanbruegge, @vlad-zhukov, @zcei and all others! 👏

Changes since v1.0.0-beta


  • Added a styleLoader option to css() and css.modules() blocks. With it it's now possible to pass options to the style-loader or remove it from loaders completely.


  • Breaking change: Renamed package from babel6 to babel and moved babel-core to be a peer dependency (#217)


  • More useful error message when passing invalid blocks to createConfig() (#171)
  • Less noisy default options


  • Removed reactHot (#214)
  • Update webpack-dev-server to v2.6.1, now compatible with webpack v3 (#179)
  • Less noisy default options
  • Make webpack a peer dependency, make compatible with webpack v3 (#174)


  • Breaking change: Drop webpack 2 support, update extract-text-webpack-plugin to v3


  • Breaking change: Remove plugins argument
  • Add minimize option


  • Add minimize option


This package is completely new!


  • Added setEnv() (#206)
  • Make resolve() prepend custom extensions (#177)
  • Let core createConfig() validate the passed setters (#171)
  • Made webpack a peer dependency (#169)
  • Made compatible with webpack v3 (#169)


  • Renamed babel6 to babel
  • The new version of extract-text requires webpack v3
  • Add @webpack-blocks/uglify
By Andy Wermke • Published on June 12, 2017

Introducing match() #163

Explicit is better than implicit and inconsistent fileType parameters are a disgrace. That's why there shall be match()!

You can now use match() to specify on which files to apply certain loaders. Works with every block that adds a loader, like babel, css, elm, postcss, sass, ...

The blocks still work without match(), though, in order to not break compatibility.

const { createConfig, css, file, match, postcss, url } = require('webpack-blocks')
const path = require('path')

module.exports = createConfig([
  babel(),            // matches *.js, *.jsx outside node_modules/ by default
  match('*.css', { exclude: path.resolve('node_modules') }, [
  match(['*.gif', '*.jpg', '*.jpeg', '*.png', '*.svg', '*.webp'], [

Using match() with your own blocks

Don't forget to update your own blocks. It's quite simple:

function myCssBlock () {
  return (context, { addLoader }) => addLoader(
      test: /\.css$/,    // provide a sane default
      use: [
    }, context.match)    // use what was set using match()


  • context.fileType is now deprecated, since we have match()
  • fileType parameters in @webpack-blocks/assets blocks & @webpack-blocks/extract-text have been deprecated and will be removed soon
By Andy Wermke • Published on January 27, 2017

Another step towards v1.0, containing one potentially breaking change: The default CSS loader does not exclude the node_modules/ directory anymore. So you can now just require('some-other-package/stylesheet.css') without additional configuration.

As the 1.0 release is getting closer I would like to encourage you to provide feedback, so we get to know what works well and what has to be improved.

Please share your experiences when using webpack-blocks, no matter if you encounter any problems or everything worked just fine right away! 👍

How to upgrade

Just open your package.json and upgrade the @webpack-blocks/* dependencies to ^0.4.0. Then run npm install / yarn.

Make sure you update all webpack-block packages at once, since the new default CSS loader behavior made changes in css-modules and postcss blocks necessary as well.


  • Breaking change: Default CSS loader does not exclude node_modules/ anymore
  • Added createConfig.vanilla() (#80, #95)
  • Made dev-server composable (#78)

Under the hood:

  • Added webpackVersion to context
  • Using webpack-merge v2.3 instead of v0.14
  • Using webpack v2.2 instead of the RC (webpack2 and related blocks only, of course)
  • Fixed: The config object passed to blocks as parameter could contain duplicate values (#79)
  • Added application/x-typescript file type
  • Added text/x-less file type


Looking for TypeScript support? Then there is good news: @jvanbruegge just added the typescript and tslint blocks.

Check 'em out if you would like to give static typing a try 😉

By Andy Wermke • Published on December 23, 2016

ğŸŽ„ Santa Clause is coooooming to town... with a jolly song on his lips and bag full of features and improvements over his shoulder! ğŸŽ„

A version bump to 0.3 might not sound very spectacular, but this release is! Consider it one step before the 1.0 release candidate.

Update to v0.3

Since there has been a breaking change affecting all blocks, make sure that you upgrade all blocks to ^0.3.0 together. An update note has been added to the README as well.

So what has been done?

Context object

There is one major breaking change under the hood: fileTypes is not passed to blocks as first parameter anymore, but rather a context object containing a fileType property (which does the same).

The real gimmick here is that you can modify this context object to save metadata you need somewhere else, but that is not supposed to be put into the webpack config object. Very useful in combination with hooks (see below).

Webpack 2

The webpack 2 blocks have been merged into the master branch and logic that is common to webpack 1.x and 2.x blocks has been moved to a new @webpack-blocks/webpack-common package.

Also the webpack2 block is now using the webpack 2 release candidate version and supports webpack performance budgets (use performance()).


Another great feature to achieve things that could not be done with webpack-blocks before. For instance you can now use defineConstants() to instantiate a webpack.DefinePlugin instance. So far so good, but you can use defineConstants() multiple times and end up having one single webpack.DefinePlugin instance containing the constants of all defineConstants() calls.

Check out How to create your own blocks for details.


There a new sharp tool in the shed: group(). It lets you combine a set of blocks to a new block that provides the functionality of all those single blocks. Now that there are hooks allowing for more intelligent merging you can now write powerful presets if you get bored during the holidays!

How to create one? Read the manual 😉


The babel6 block now supports include (additionally to exclude), presets and plugins options. So you can now configure babel from within your webpack configuration using webpack-blocks.


Special thanks again goes to @eXon for steady contribution and feedback! 🙂

Merry Christmas!

By Andy Wermke • Published on October 13, 2016

This is the first published release of webpack-blocks. Read about its usage in the README.

Try it and leave some feedback!

Available webpack blocks


Typescript Types


GitHub Stargazers
Community Interest
Number of Forks


Last Commit
Open Issues
Closed Issues
Open Pull Requests
Closed Pull Requests


Versions Released
Latest Version Released
Apr 27, 2020
Current Tags


Commits: 57
Commits: 32
Commits: 18
Commits: 14
Commits: 13
Commits: 13
Commits: 10
Commits: 9
Commits: 9
Commits: 5
Commits: 5
Commits: 4
Commits: 4
Commits: 2
Commits: 2