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)

Table of contents

• 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

• assets
• babel
• dev-server
• elm
• eslint
• extract-text
• postcss
• sass
• tslint
• typescript
• uglify

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

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

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

print(module.exports)

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

/**
 * @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
      )
    )
}

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']
    }
  })
])

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

Like what you see?

Support webpack-blocks by giving feedback, contributing to this repository, publishing new webpack blocks or just by 🌟 starring the project!

Contributors

These awesome people have helped webpack-blocks by adding features, fixing bugs and refactoring code. You can become one of them!

License

MIT