node package manager
We need your input. Help make JavaScript better: Take the 2017 JavaScript Ecosystem survey »


Minimalist boilerplate for Webpack +/- Express

  • Hot loading for both client & server
  • Code in es2015
  • CSS module + postcss + autoprefixer
  • Assets minification for production
  • Client files hashing for caching
  • Focus on your app logics, leave the build tools to others

To start

mkdir myApp
cd myApp
npm init
npm i -D mwb # install (i) mwb as devDependency (-D) 
npm run mwb init # generate the boilerplate with an express server 
npm run mwb initMin # generate the boilerplate without a server 
npm run dev # start live coding & editing in development mode 
npm run bundle # bundling the app for production 

Tested in node 8+, npm 5+

Directory structure:

 ├─ /build/
 ├─ /tool/
 └─ /src/ 
     ├─ /client/
     |    └─ entry.js
     ├─ /share/
     ├─ /server/
     |     ├─ entry.js
     |     ├─ app.js 
     |     └─ main.js
     └─ /public/
           └─ favicon.ico

How it works:

  • After initiation, an entry.js file is placed in the src/client and src/server folder
  • All default webpack config files are in the tool folder, you can override these
  • npm run dev uses webpack to compile and watch these files and output them into the build folder -> client.js and server.js
  • serverBundle.js is run automatically and will be served at localhost:3000 (default using express js)
  • When you edit the files in the source folder, webpack re-compile required files
  • To enable hot module replacement, add if ( {} in your code
  • Default webpack.config.js is in the tool directory


Included loaders:

  • babel-loader with presets (env, stage-0, react), plugins (transform-runtime) and cacheDirectory (true).
  • css!postcss loaders for css with autoprefixer, postcss-import, postcss-nested, postcss-css-variables
  • url-loader for everything else with limit=10000 & name=[name]_[hash:7].[ext]

Style sheet is extracted by extract-text-webpack-plugin for the initial chunk. The subsequent chunks will be inlined using style-loader in the client. css module is applied to files with name xxx.module.css. You should not mix global and local css, i.e. in global.css don't do @import './local.module.css'; and vice versa, in local.module.css don't do @import './global.css'. On server, null-loader is applied to global.css but css?module to local.module.css, the extracted styles.css will be deleted on server when built for production.

Included plugins

  • extract-text-webpack-plugin
  • html-webpack-plugin using template at ./src/share/index.html
  • webpack.optimize.AggressiveMergingPlugin
  • webpack.optimize.UglifyJsPlugin
  • webpack.DefinePlugin({ 'process.env.APP_ENV': '"node"' })for server
  • webpack.DefinePlugin({ 'process.env.APP_ENV': '"web"' }) for clients (browser and cordova)
  • webpack.DefinePlugin({ 'process.env.CORDOVA': true }) for cordova app
  • webpack.DefinePlugin({ 'process.env.TEST': true }) for testing
  • webpack.DefinePlugin({ 'process.env.NODE_ENV': '"development"' }) in development mode
  • webpack.DefinePlugin({ 'process.env.NODE_ENV': '"production"' }) in production mode to aid dead code elimination during minification
  • offline-plugin with minification on in production mode for client

Express server

  • Listen to 3000 by default or process.env.PORT
  • Use compression middleware, then static('./build/public') middleware
  • Server code is hot replaced in development mode, but NOT in production mode
  • All native modules and assets.json are excluded (treated as external) by webpack using /^[@a-z][a-z/\.\-0-9]*$/i, and /^.?assets\.json$/i in server, this speeds up build time


  • All codes wrapped inside if (process.env.NODE_ENV !== 'production') {} or if (process.env.NODE_ENV == 'development') {} or if( {} are removed for production
  • source map is set to cheap-module-eval-source-map for development
  • source map is NOT included in production mode
  • client_[chunkhash:7].js vendor_[chunkhash:7].js & styles_[contenthash:7].css in production mode for caching
  • ~ is aliased to the src directory. For example, import '~/server/myModule'


npm run mwb initMongo

This add the latest mongodb native driver to the app. This also add a file named mongo.js into the src/server folder. The mongo.js file contains and export the default connection. In an imported file, use async & await to retrive the connection and db.

React & Redux

Writing tests


Cordova integration

Extending the configs


You can update simply by typing

npm i -D mwb

The tool directory will be renamed to tool.{timestamp}