@webpack-contrib/schema-utils

What is @webpack-contrib/schema-utils?

@webpack-contrib/schema-utils is a utility library for validating options against JSON schemas. It is commonly used in webpack plugins and loaders to ensure that user-provided options conform to expected formats.

What are @webpack-contrib/schema-utils's main functionalities?

Schema Validation

This feature allows you to validate an options object against a JSON schema. If the options do not match the schema, an error will be thrown.

const validate = require('@webpack-contrib/schema-utils');
const schema = {
  type: 'object',
  properties: {
    option: {
      type: 'string'
    }
  },
  additionalProperties: false
};
const options = { option: 'value' };
validate(schema, options, { name: 'MyPlugin' });

Custom Error Messages

You can catch validation errors and provide custom error messages to make debugging easier.

const validate = require('@webpack-contrib/schema-utils');
const schema = {
  type: 'object',
  properties: {
    option: {
      type: 'string'
    }
  },
  additionalProperties: false
};
const options = { option: 123 };
try {
  validate(schema, options, { name: 'MyPlugin' });
} catch (error) {
  console.error('Custom error message:', error.message);
}

Other packages similar to @webpack-contrib/schema-utils

ajv

Ajv is a JSON schema validator that is highly performant and supports JSON Schema draft-07 and later. It is more feature-rich compared to @webpack-contrib/schema-utils and can be used for more complex validation scenarios.

joi

Joi is a powerful schema description language and data validator for JavaScript objects. It offers a more expressive and flexible API compared to @webpack-contrib/schema-utils, making it suitable for a wider range of validation tasks.

yup

Yup is a JavaScript schema builder for value parsing and validation. It is similar to Joi but is more lightweight and has a more modern API. It is often used in React applications for form validation.

README

schema-utils

Webpack Schema Validation Utilities

Validates options objects against a JSON Schema and displays the output beautifully.

Requirements

This module requires a minimum of Node v6.9.0 and Webpack v4.0.0.

Getting Started

To begin, you'll need to install schema-utils:

$ npm install @webpack-contrib/schema-utils --save-dev

API

When using the API directly, the main entry point is the serve function, which is the default export of the module.

const validate = require('@webpack-contrib/schema-utils');
const schema = require('path/to/schema.json');
const target = { ... }; // the options object to validate
const name = '...'; // the load or plugin name validate() is being used in

validate({ name, schema, target });

serve(options)

Returns true if validation succeeded, false validation failed and options allow the function to return a value. (see options below).

options

Type: Object

Options for initializing and controlling the server provided. The option names listed below belong to the options object.

exit

Type: Boolean Default: false

If true, will instruct the validator to end the process with an error code of 1.

log

Type: Boolean Default: false

If true, will instruct the validator to log the results of the validation (in the event of a failure) in a webpack-style log output. This is typically used with throw: false.

name

Type: String Default: undefined Required

A String specifying the name of the loader or plugin utilizing the validator.

schema

Type: String|Object Default: undefined Required

A String specifying the filesystem path to the schema used for validation. Alternatively, you may specify an object containing the JSON-parsed schema.

target

Type: Object Default: undefined Required

An Object containing the options to validate against the specified schema.

throw

Type: Boolean Default: true

By default the validator will throw an error and display validation results upon failure. If this option is set to false, the validator will not throw an error. This is typically used in situations where a return value of false for validate() is sufficient, a stack trace is uneeded, or when webpack-style log output is preferred.

Examples

Below is a basic example of how this validator might be used:

# schema.json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "test": {
      "anyOf": [
        { "type": "array" },
        { "type": "string" },
        { "instanceof": "RegExp" }
      ]
    },
    "transform": {
      "instanceof": "Function"
    },
    "sourceMap": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Use in a Loader

const { getOptions } = require('loader-utils');
const validate = require('@webpack-contrib/schema-utils');

import schema from 'path/to/schema.json'

function loader (src, map) {
  const options = getOptions(this) || {};

  validate({ name: 'Loader Name', schema, target: options });

  // Code...
}

Use in a Plugin

const validate = require('@webpack-contrib/schema-utils');
const schema = require('path/to/schema.json');

class Plugin {
  constructor (options) {
    validate({ name: 'Plugin Name', schema, target: options });

    this.options = options;
  }

  apply (compiler) {
    // Code...
  }
}

License

MIT