README.md

webpack-validator

Validate your webpack configs with joi

Note: webpack v2 has built-in validation for configuration (you don't have to do anything, it just works). Due to this, webpack-validator is unlikely to make significant changes. While pull requests will be reviewed and can be merged (for webpack v1 support), project maintainers are unlikely to put a lot of much effort into the maintenance of the project.

Writing webpack configs is brittle and error-prone. This package provides a joi object schema for webpack configs. This gets you a) static type safety, b) property spell checking and c) semantic validations such as "loader and loaders can not be used simultaneously" or "query can only be used with loader, not with loaders".

You're very welcome to give feedback & PR's.

Example

Take this simple webpack config. It has a tiny, hard to spot error. Can you find it?

var config = {
  module: {
    loaders: [
      { test: /\.js$/, loaders: 'babel-loader', exclude: /node_modules/ }
    ]
  },
  output: {
    library: 'Redux',
    libraryTarget: 'umd'
  },
  plugins: [
    new webpack.optimize.OccurenceOrderPlugin(),
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify(env)
    })
  ]
};

webpack-validator makes it easy:

Usage

There are two ways to use webpack-validator: a) "programmatically" by wrapping your webpack config object with a validation function or b) by using a command line interface.

For the first approach, add this in your webpack.config.js:

const validate = require('webpack-validator');

module.exports = validate({ /* ... your webpack config */ });

Now run webpack. Either everything is green and the build continues or joi will let you know what's wrong and the build won't continue.

If your webpack config is an array of configs instead of a single object, the above doesn't quite work. Add this in your webpack.config.js instead:

const validate = require('webpack-validator').validateRoot;

module.exports = validate({ /* ... your webpack config */ });

CLI

For CLI usage you probably want to install the tool globally (npm install -g webpack-validator) first. Then just run webpack-validator <your-config>.

Customizing

Schema

If you need to extend the schema, for example for custom top level properties or properties added by third party plugins like eslint-loader (which adds a toplevel eslint property), do it like this:

const validate = require('webpack-validator')
const Joi = require('webpack-validator').Joi

// This joi schema will be `Joi.concat`-ed with the internal schema
const yourSchemaExtension = Joi.object({
  // this would just allow the property and doesn't perform any additional validation
  eslint: Joi.any()
})

const config = { /* ... your webpack config */ }

module.exports = validate(config, { schemaExtension: yourSchemaExtension })

Rules

Some validations do more than just validating your data shape, they check for best practices and do "more" which you might want to opt out of / in to. This is an overview of the available rules (we just started with this, this list will grow :)):

• no-root-files-node-modules-nameclash (default: true): this checks that files/folders that are found in directories specified via webpacks resolve.modules option do not nameclash with node_modules packages. This prevents nasty path resolving bugs (for a motivating example, have a look at this redux issue).
• loader-enforce-include-or-exclude (default: false): enforce that loader objects use include or/and exclude, throw when neither is supplied. Without supplying one of these conditions it is too easy to process too many files, for example your node_modules folder.
• loader-prefer-include (default: false): enforce that loader objects use include and not exclude. exclude makes it easy to match too many files, which might inadvertently slow your build down.

You opt in/out of rules by using the rules option:

module.exports = validate(config, {
  rules: {
    'no-root-files-node-modules-nameclash': false,
  },
})

Note: This is not yet implemented via cli options, the default rules will apply in that case.

Quiet Mode

If you want to mute console output apart from errors, set --quiet (-q) or validate(config, { quiet: true }). This is particularly useful if you are using webpack --json as you'll want to avoid writing additional text to the JSON output.

Validate all package.json scripts

It is possible to use the CLI to validate all your package.json scripts related configurations at once by using --all-scripts (-a). The system will try to guess the convention you are using and then executes validation against each script target based on that.

Advanced Usage

If you need to access the validation results directly and want to control the side-effects (i.e. console.log output, process.exit(1) on fail behaviour) yourself, you can call the validation function like so: validate(config, { returnValidation: true }). This will make 1) the function return the validation results instead of your configuration and 2) not perform any side effects.

Support

Because this module uses the amazing Joi validation library, this module only supports Node >=4.0.0.

License

MIT