webpack-validator
v3.0.1
Published
Validate your webpack config with joi
Downloads
11,765
Readme
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.root
option do not nameclash withnode_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/andexclude
, throw when neither is supplied. Without supplying one of these conditions it is too easy to process too many files, for example yournode_modules
folder. - loader-prefer-include (default: false): enforce that loader objects use
include
and notexclude
.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