node package manager
Orgs are free. Discover, share, and reuse code in your team. Create a free org »

webpack-digest

Webpack Digest Crane

Webpack Digest

Commitizen Friendly Semantic Release
Build Status Coverage Report NPM Version License FOSSA Status Canonical Code Style

Webpack Digest is a reusable and extendable Webpack 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.

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 Default 8080, 8090 when NODE_ENV='development'
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. src
STATIC_PATH The directory where Webpack will deposit the resulting project relative to project root. /public
CACHE_PATH Path to store temporary cache files /node_modules/.cache/
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
POSTCSS Path to postcss.config.json /postcss.config.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
TESTCONFIG Path to testconfig.js. This optional script is picked up by the provided Jest config to setup additional test suites such as enzyme /testconfig.js
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
CONFIG Path to webpack.config.js. See Webpack Config for more details. /webpack.config.js or default config from Webpack Digest

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/lib/express/start.js",
  "start:dev": "cross-env NODE_ENV='development' PORT=8090 node node_modules/webpack-digest/lib/express/start.js",
  "build": "cross-env webpack --config node_modules/webpack-digest/lib/webpack.config.js --progress --colors --display-error-details",
  "build:dev": "cross-env NODE_ENV='development' webpack --config node_modules/webpack-digest/lib/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 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/lib/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 default express app configuration. Simply create a server.extend.js file and import webpack-digests app.js. Note that to avoid complications with non-root routes, the / route and HTML5 /* catch-all are not implemented in the default app.js; they will have to be provided. After extending, serve express or use the provided server.js:

 
/* Example server.extend.js */
var app = require('webpack-digest/lib/express/app.js');
var proxy = require('http-proxy-middleware');
 
app.use(
  '/',
  express.static(path.join('public'))
);
 
// For HTML5 Routing
app.all(
  '/*',
  (request, response) => {
    response.sendFile(path.join('public', 'index.html'));
  }
);
 
app.get('/env', function(req, res){
  res.json({
    env: 'qa'
  })
})
 
app.use('/api', proxy({
  target: 'http://localhost:9090',
  changeOrigin: true
}))
 
/* Optionally, serve with provided server.js */
var server = require('webpack-digest/lib/express/server.js');
 
server(app);

Then remember to reference your server.extend.js in the projects package.json scripts:

"scripts"{
  "start": "cross-env PLATFORMS='react,cssModules' node server.extend.js"
  ...
}

Webpack Config

It's also easy to extend webpack-digests Webpack configuration. Create a webpack.config.js in the root of your project, then import webpack-digests configuration and extend to your liking. Projects such as webpack-merge and webpack-config can help extend the generated config file.

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

A file named webpack.config.js in your root directory should be picked up automatically by the webpack command and the --config option can be ommitted:

"scripts"{
  ...
  "build": "cross-env webpack --progress --colors --display-error-details"
}

To clarify, if you use a different file name or path, you can refer to your extended config explicitly in your build scripts:

"scripts"{
  ...
  "build": "cross-env webpack --config webpack.config.js --progress --colors --display-error-details"
}

If you are using or extending the provided app and express server, then follow same as above; a Webpack config called webpack.config.js located in the project root will be resolved automatically. If your extended config has a different name or path, the default express will require the path given via the CONFIG environment variable:

"scripts"{
  "start": "cross-env CONFIG='configs/webpack.js' node node_modules/webpack-digest/lib/express/start.js"
  ...
}

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/lib/jest/config.js --no-cache --coverage",
  "test:dev": "cross-env node_modules/.bin/cross-env PLATFORMS='react,cssModules' jest --config node_modules/webpack-digest/lib/jest/config.js --no-cache --watch"
}

* Note : Remember to include all relevant environment variabels from your production and development scripts in your test scripts. Also remember the TESTCONFIG option for additional test suite configuration when using the provided Jest config.

License

GPLv3