@terse/webpack NPM

@terse/webpack

Webpack simplified in a fluent API with presets & an escape hatch so you're not locked in.

Why?

Webpack is powerful, but extremely complicated for newcomers to use.
Merging configuration objects is exceedingly difficult and error-prone.
Using Webpack on both the server & client is necessary once you leverage Webpack's APIs (e.g. require.context, require.ensure).
There are tons of configuration pitfalls that can negatively impact your build that you shouldn't have to know about.
It's a full-time job keeping up-to-date with the latest build optimizations.
Most React boilerplates have similar configuration, but no abstraction for composition.

Why Not?

You're comfortable with Webpack configuration.
You consider abstraction bad (e.g. "magic" or "indirection").
You have to get access to the "bare-metal" APIs.
TODO - Check Twitter for more cynical responses.

How?

This project attempts to solve these problems via:

Built on Webpack2, with the latest advancements.
Simple, fluent API that takes the guess-work out.
Escape hatch to copy/paste the generated, raw config.
Optional .presets for getting started quickly.
Functional reducers that you can override to customize the output.
Each action creates a new config, so you can easily compose them.

Upcoming features:

.presets:
- .autoinstall() - Install missing dependencies.
- .conventions() - Default input & output sources.
- .hot() - Simplify HMR.
- .offline() - Add offline support to your app.
- .react() - Quickly get started with React.
terse-webpack CLI - Start coding without any initialization.
GUI - Get started on a new project with a few clicks.

Example

// webpack.config.js
module.exports = require("@terse/webpack").api()
  .entry("./src/client.js")
  .loader("babel", ".js", {
    exclude: /node_modules/,
    query: { cacheDirectory: true },
  })
  .modules("./lib")
  .output("build/client")
  .target("web")
  .when("development", function(api) {
    return api
      .entry({
        client: [
          "webpack-hot-middleware/client?reload=true&timeout=2000",
          "./src/client.js",
        ],
      })
      .plugin("npm-install-webpack-plugin")
      .plugin("webpack.HotModuleReplacementPlugin")
      .plugin("webpack.NoErrorsPlugin")
      .sourcemap("source-map")
    ;
  })
  .getConfig()
;

Generates client.js in the build directory from ./src/client.js.
Parses .js files (excluding node_modules) with Babel.
Searches node_modules and ./lib for non-relative files.
Outputs assets to ./build/client.
Target platform is web (vs. node).
When NODE_ENV is development: a. Override client.js to support HMR. b. Add npm-install-webpack-plugin to auto-install missing dependencies. c. Add HMR support. d. Enable source-map-style source maps (e.g. .map files).

Dependencies

I recommend using this against the latest Node + NPM v3.

Installation

npm install @terse/webpack

Usage

View the example.

Replace the contents of webpack.config.js (and others) with:

module.exports = require("@terse/webpack").api()
  ...
  .getConfig()
;

It's crucial to call .getConfig() to return the Webpack configuration.

With the upcoming .presets, it'll be as simple as:

module.exports = require("@terse.webpack").api()
  .presets("autoinstall", "hot", "react", "offline")
  .target("web")
  .getConfig()
;

API

.api([customFeatures[, customReducers]])
Begins fluent interface, optionally accepted an array of custom features and custom reducers.
.alias(name[, pathOrName])
Maps a package name (e.g. react) to another library (e.g. react-lite) or to a path (e.g. ./node_modules/react).
.context(path)
Config files are relative to this folder. (Default: process.cwd())
.env(environment)
Overrides NODE_ENV (defaults to development) the build is for.
.externals(...[Function, RegExp, String])
Prevents Webpack from bundling matching resources.
.loader(name[, extensions = ".js"[, options]])
Add a loader for the given extension(s) with the given settings.
.modules(path)
Lookup non-relative (e.g. my-cool-lib) modules in this folder as well as node_modules.
.node(options)
Override built-in Node constants & libs (e.g. __dirname, __filename)
.output(pathOrOptions)
Set the output path, or specify the entire Webpack output configuration.
.plugin(name, ...args)
Installed automatically with the given arguments.
.preLoader(name[, extensions = ".js"[, options]])
Just like .loader, but is ran before all other loaders.
.sourcemap(type)
Add a source map to the build.
.target(runtime)
Either node or web.
.getConfig()
Returns the Webpack configuration
- .toString()
  Returns the Webpack configuration as a string.
.getState()
Returns the normalized configuration (prior to reducing).
- .toString()
  Returns a string of the normalized configuraiton.