node package manager

webpack-digest

Webpack Digest


Webpack Digest is a reusable and extendable Webpack2 configuration. Webpack Digest can be used to quickly start new projects or maintain several projects with a single configuration.

The shared configuration offers sane defaults for common loaders and plugins. So far assets include .html, .css, .js, .svg, .png, .jpg, .ico, .gif, .woff(2), .eot, and .ttf. Additional loaders are configured for React (.jsx), Typescript (.ts, .tsx), and Sass (.sass, .scss). Defaults for index.html, favicon, linters (esling, tslint, stylelint), Babel, and Express are configured - but can be overridden or extended. Hot Module Replacement (HMR) and React Hot Loader 3 are configured for development. Development builds use HMR, skip source minification, and lazily generate source maps. A Jest configuration is also provided.

Warning: this project is still alpha quality with possible breaking changes with each release. Typescript and Angular2's Hot Loader are in progress. Please see To Do for areas of improvement.


Install

npm install webpack-digest

It's also suggested cross-env is installed globally to assist with cross-platform environment variable definitions required in the package.json scripts. cross-env is used in the examples below.

npm install -g cross-env

Options


This configuration will generate both development and production builds. The following environment variables can be set to configure the builds:

Environment Variable Description Default Options
NODE_ENV Use either production or development. Production features include minification, while development features include linting and HMR. production
PORT The express host port 8080
DASHBOARD Use webpack-dashboard on [on|off]
LIBRARY Toggle UMD library creation instead. This generates a bundle without dependencies. false [true|false]
SOURCE_MAPS Toggle source map generation true [true|false]
SHORT_NAME An optional shorter name to be used in bundle generation. Useful when generating libraries. The name property in package.json
SRC_PATH The project files directory relative to project root. .
STATIC_PATH The directory where Webpack will deposit the resulting project relative to project root. /public
INDEX Path to index.htm /SRC_PATH/index.htm or what comes packaged with **Webpack Digest**
FAVICON Path to favicon.ico /SRC_PATH/favicon.ico or what comes packaged with **Webpack Digest**
PLATFORMS Comma delimited list of platforms can enable different loader behaviours. cssModules, [react|preact], typescript, angular
ESLINT Path to eslintrc.json /eslintrc.json or what comes packaged with Webpack Digest
STYLELINT Path to stylelintrc.json /stylelintrc.json or what comes packaged with Webpack Digest
STYLELINT_IGNORE Path to .stylelintignore /.stylelintignore or what comes packaged with Webpack Digest
TSLINT Path to tslintrc.json /SRC_PATH/tslint.json or what comes packaged with Webpack Digest
TSCONFIG Path to tsconfig.json /tsconfig.json or what comes packaged with Webpack Digest
POLYFILLS Path to polyfills.js /polyfills.js or what comes packaged with Webpack Digest
SERVER Path to server.extend.js. See Express for more details. /server.extend.js
CONFIG Path to config.extend.js. See Webpack Config for more details. /config.extend.js

Setup


npm


To run with npm, setup scripts in your project's package.json to easily set the environment variables:

"scripts"{
  "start": "cross-env node node_modules/webpack-digest/src/app.js",
  "start:local": "cross-env NODE_ENV=development PORT=8090 node node_modules/webpack-digest/src/app.js",
  "build": "cross-env webpack --config node_modules/webpack-digest/src/webpack.config.js --progress --colors --display-error-details",
  "build:local": "cross-env NODE_ENV=development webpack --config node_modules/webpack-digest/src/webpack.config.js --progress --colors --display-error-details",
  "clean": "rm -rf static && rm -rf .cache/"
}

Then run one of the scripts. For example:

npm run start:local

Maven


webpack-digest can also be configured in Maven projects using <a href"https://github.com/eirslett/frontend-maven-plugin" target="_blank">frontend-maven-plugin. To use with Maven, set the frontend-maven-plugin arguments and environment variables in the pom.xml:

<execution>
  <id>webpack install</id>
  <goals>
    <goal>webpack</goal>
  </goals>
  <configuration>
    <arguments>--config node_modules/webpack-digest/src/webpack.config.js --display-error-details</arguments>
    <environmentVariables>
      <SRC_PATH>src/main/resources/ui</SRC_PATH>
      <STATIC_PATH>src/main/resources/public</STATIC_PATH>
      <PLATFORMS>react,cssModules</PLATFORMS>
      <NODE_ENV>${NODE_ENV}</NODE_ENV>
    </environmentVariables>
  </configuration>
</execution>

Plugins

CSS Modules

When CSS modules are used, a CSS file can be set explicitly global via the .g.css extension. For example, styles.g.css would be loaded globally, while styles.css would load as a CSS module. CSS from packages are always global.

When using React, React CSS modules Babel plugin is used, and so should the styleName property in your components.


Extending

Express

It's easy to extend the express instance with a function. webpack-digest will accept a file path to the function, or you can simply create a server.extend.js file in the root of the project. The function is passed the express instance which can then be extended. For example:

/* server.extend.js */
var proxy = require('http-proxy-middleware');
 
function rest(app) {
 
  app.get('/env', function(req, res){
    res.json({
      env: 'qa'
    })
  })
 
  app.use('/api', proxy({
    target: 'http://localhost:9090',
    changeOrigin: true
  }))
 
}
 
module.exports = rest;

Webpack Config

It's also possile to extend Webpack Digests generated webpack config with a function. webpack-digest will accept a file path to the function or a config.extend.js file in the root of the project. The function is passed the generated config object which can then be extended. The function must return a resulting config. For example:

/* config.extend.js */
var webpackDigest = require('webpack-digest/src/webpack.config.js');
 
function extend(config) {
  /* Modify the config */
  return config;
}
 
module.exports = extend(webpackDigest);

Then reference your config.js in your package.json scripts. For example:

"scripts"{
  "start": "cross-env PLATFORMS='react,cssModules' CONFIG='config.extend.js' node node_modules/webpack-digest/src/app.js",
  "start:local": "cross-env NODE_ENV=development PLATFORMS='react,cssModules' PORT=8090 CONFIG='config.extend.js' node node_modules/webpack-digest/src/app.js",
  "build": "cross-env PLATFORMS='react,cssModules' webpack --config config.extend.js --progress --colors --display-error-details",
  "build:local": "cross-env NODE_ENV=development PLATFORMS='react,cssModules' webpack --config config.extend.js --progress --colors --display-error-details",
  "clean": "rm -rf static && rm -rf .cache/"
}

Packages such as webpack-merge and webpack-config can help extend the generated config file.


Testing

Jest

Because Webpack and Babel configurations are not in the root directory, Jest can be tricky to setup in this kind of configuration. A Jest configuration is provided, or it can be copied and modified further. To use the provided Jest configuration, simply include the following scripts in your package.json*:

scripts: {
...
"test": "cross-env node_modules/.bin/cross-env PLATFORMS='react,cssModules' jest --config node_modules/webpack-digest/src/jest.config.json --coverage --no-cache",
"test:dev": "cross-env node_modules/.bin/cross-env PLATFORMS='react,cssModules' jest --config node_modules/webpack-digest/src/jest.config.json --coverage --watch --no-cache ",
}

* Note : Remember to include all relevant environment variabels from your production and development scripts in your test scripts.


To Do

Issues
Add unit tests for the default configuration

License

GPLv3