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
npm install --save-dev webpack webpack-blocks
# or
yarn add --dev webpack webpack-blocksThe 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.
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()
])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.
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 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
- 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!
- Extensibility first
- Uniformity for easy composition
- Keep everything configurable
- But provide sane defaults
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.
Support webpack-blocks by giving feedback, contributing to this repository, publishing new webpack blocks or just by 🌟 starring the project!
These awesome people have helped webpack-blocks by adding features, fixing bugs and refactoring code. You can become one of them!
MIT