webpack-blocks

Functional building blocks for your webpack config: easier way to configure webpack and to share configuration between projects.

Ready to use blocks to configure popular tools like Babel, PostCSS, Sass, TypeScript, etc., as well as best practices like extracting CSS — all with just one line of configuration.

Note: This is the documentation of webpack-blocks v2, compatible with webpack 4. Check out the v1 branch if you need to be compatible with webpack 3 or older.

"Finally, webpack config done right. (...) Webpack clearly wants to stay low-level. So it makes total sense to outsource configuring it to well designed blocks instead of copy-paste."

Dan Abramov via twitter (Co-author of Redux, Create React App and React Hot Loader)

Installation
Example
More examples
Custom blocks
Available webpack blocks
Helpers
Shorthand setters
Third-party blocks
Design principles
FAQ
Like what you see?
Contributors
License

Installation

npm install --save-dev webpack webpack-blocks
# or
yarn add --dev webpack webpack-blocks

Example

The following sample shows how to create a webpack config with Babel support, dev server and Autoprefixer.

const webpack = require('webpack')
const {
  createConfig,
  match,

  // Feature blocks
  babel,
  css,
  devServer,
  file,
  postcss,
  uglify,

  // Shorthand setters
  addPlugins,
  setEnv,
  entryPoint,
  env,
  setOutput,
  sourceMaps
} = require('webpack-blocks')
const autoprefixer = require('autoprefixer')
const path = require('path')

module.exports = createConfig([
  entryPoint('./src/main.js'),
  setOutput('./build/bundle.js'),
  babel(),
  match(['*.css', '!*node_modules*'], [
    css(),
    postcss({
      plugins: [
        autoprefixer({ browsers: ['last 2 versions'] })
      ]
    })
  ]),
  match(['*.gif', '*.jpg', '*.jpeg', '*.png', '*.webp'], [
    file()
  ]),
  setEnv({
    NODE_ENV: process.env.NODE_ENV
  }),
  env('development', [
    devServer(),
    devServer.proxy({
      '/api': { target: 'http://localhost:3000' }
    }),
    sourceMaps()
  ]),
  env('production', [
    uglify(),
    addPlugins([new webpack.LoaderOptionsPlugin({ minimize: true })])
  ])
])

See shorthand setters and helpers documentation.

All blocks, like babel or postcss are also available as their own small packages, webpack-blocks package wraps these blocks, shorthand setters and helpers as a single dependency for convenience.

More examples

CSS modules:

const { createConfig, match, css } = require('webpack-blocks')

// ...

module.exports = createConfig([
  // ...
  match(['*.css', '!*node_modules*'], [
    css.modules()
  ]
])

TypeScript:

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

// ...

module.exports = createConfig([
  // ...
  typescript()
])

Custom blocks

Need a custom block? A simple block looks like this:

module.exports = createConfig([
  // ...
  myCssLoader(['./styles'])
])

function myCssLoader() {
  return (context, { merge }) =>
    merge({
      module: {
        rules: [
          Object.assign(
            {
              test: /\.css$/,
              use: ['style-loader', 'my-css-loader']
            },
            context.match // carries `test`, `exclude` & `include` as set by `match()`
          )
        ]
      }
    })
}

If we use myCssLoader in match() then context.match will be populated with whatever we set in match(). Otherwise there is still the test: /\.css$/ fallback, so our block will work without match() as well.

Check out the sample app to see a webpack config in action or read how to create your own blocks.

Available webpack blocks

Helpers

Helpers allow you to structure your config and define settings for particular environments (like production or development) or file types.

group
env
match
when

Shorthand setters

Shorthand setters gives you easier access to common webpack settings, like plugins, entry points and source maps.

addPlugins
customConfig
defineConstants
entryPoint
performance
resolve
setContext
setDevTool
setEnv
setOutput
sourceMaps

Third-party blocks

webpack-blocks-happypack — HappyPack
webpack-blocks-less — Less
webpack-blocks-purescript — PureScript
webpack-blocks-server-source-map — source map for server bundle
webpack-blocks-split-vendor — vendor bundle
webpack-blocks-ts — TypeScript using ts-loader instead of awesome-typescript-loader
webpack-blocks-vue — Vue

Missing something? Write and publish your own webpack blocks!

Design principles

Extensibility first
Uniformity for easy composition
Keep everything configurable
But provide sane defaults

FAQ

How to debug?

In case the webpack configuration does not work as expected you can debug it using q-i:

const { print } = require('q-i')

module.exports = createConfig([
  // ...
])

print(module.exports)

How does env() work?

env('development', [ ... ]) checks the NODE_ENV environment variable and only applies its contained webpack blocks if it matches the given string.

So make sure you set the NODE_ENV accordingly:

// your package.json
"scripts": {
  "build": "cross-env NODE_ENV=production webpack",
  "start": "cross-env NODE_ENV=development webpack-dev-server"
}

If there is no NODE_ENV set then it will treat NODE_ENV as if it was development. Use cross-env to make it work on all platforms.

What does defineConstants() do?

defineConstants() is a small convenience wrapper around webpack's DefinePlugin. It is composable and automatically encodes the values. Use it to replace constants in your code by their values at build time.

So having a defineConstants({ 'process.env.FOO': 'foo' }) and a defineConstants({ 'process.env.BAR': 'bar' }) in your config means the resulting webpack config will contain a single new webpack.DefinePlugin({ 'process.env.FOO': '"FOO"', 'process.env.BAR': '"BAR"' }), thus replacing any occurrence of process.env.FOO and process.env.BAR with the given values.

You can also use setEnv method to define process.env.* variables, it’s based on webpack.EnvironmentPlugin: setEnv({ FOO: 'foo' }).

What does a block look like from the inside?

A webpack block is a function and requires no dependencies at all (🎉🎉), thus making it easy to write your own blocks and share them with your team or the community.

Take the babel webpack block for instance:

/**
 * @param {object} [options]
 * @param {RegExp|Function|string}  [options.exclude]   Directories to exclude.
 * @return {Function}
 */
function babel(options = { cacheDirectory: true }) {
  return (context, util) =>
    util.addLoader(
      Object.assign(
        {
          // we use a `MIME type => RegExp` abstraction here in order to have consistent regexs
          test: /\.(js|jsx)$/,
          exclude: /node_modules/,
          use: [{ loader: 'babel-loader', options }]
        },
        context.match
      )
    )
}

Add a README and a package.json and you are ready to ship.

For more details see How to write a block.

I need some custom webpack config snippet!

No problem. If you don't want to write your own webpack block you can use customConfig():

const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const { addPlugins, customConfig } = require('@webpack-blocks/webpack')

// ...

module.exports = createConfig([
  // ...
  addPlugins([
    // Add a custom webpack plugin
    new HtmlWebpackPlugin({
      inject: true,
      template: './index.html'
    })
  ]),
  customConfig({
    // Add some custom webpack config snippet
    resolve: {
      extensions: ['.js', '.es6']
    }
  })
])

The object you pass to customConfig() will be merged into the webpack config using webpack-merge like any other webpack block's partial config.

How to compose blocks?

Got some projects with similar, yet not identical webpack configurations? Create a “preset”, a function that returns a group of blocks so you can reuse it in multiple projects:

const { createConfig, env, group, babel, devServer } = require('webpack-blocks')

function myPreset(proxyConfig) {
  return group([babel(), env('development', [devServer(), devServer.proxy(proxyConfig)])])
}

module.exports = createConfig([
  myPreset({
    '/api': { target: 'http://localhost:3000' }
  })
  // add more blocks here
])

The key feature is the group() method which takes a set of blocks and returns a new block that combines all their functionality.