schema-utils

Package for validate options in loaders and plugins.

Getting Started

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

npm install schema-utils

API

schema.json

{
  "type": "object",
  "properties": {
    "option": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

import { validate } from "schema-utils";
import schema from "./path/to/schema.json";

const options = { option: true };
const configuration = { name: "Loader Name/Plugin Name/Name" };

validate(schema, options, configuration);

schema

Type: String

JSON schema.

Simple example of schema:

{
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}

options

Type: Object

Object with options.

import { validate } from "schema-utils";
import schema from "./path/to/schema.json";

const options = { foo: "bar" };

validate(schema, { name: 123 }, { name: "MyPlugin" });

configuration

Allow to configure validator.

There is an alternative method to configure the name andbaseDataPath options via the title property in the schema. For example:

{
  "title": "My Loader options",
  "type": "object",
  "properties": {
    "name": {
      "description": "This is description of option.",
      "type": "string"
    }
  },
  "additionalProperties": false
}

The last word used for the baseDataPath option, other words used for the name option. Based on the example above the name option equals My Loader, the baseDataPath option equals options.

name

Type: Object Default: "Object"

Allow to setup name in validation errors.

import { validate } from "schema-utils";
import schema from "./path/to/schema.json";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin" });

Invalid configuration object. MyPlugin has been initialised using a configuration object that does not match the API schema.
 - configuration.optionName should be a integer.

baseDataPath

Type: String Default: "configuration"

Allow to setup base data path in validation errors.

import { validate } from "schema-utils";
import schema from "./path/to/schema.json";

const options = { foo: "bar" };

validate(schema, options, { name: "MyPlugin", baseDataPath: "options" });

Invalid options object. MyPlugin has been initialised using an options object that does not match the API schema.
 - options.optionName should be a integer.

postFormatter

Type: Function Default: undefined

Allow to reformat errors.

import { validate } from "schema-utils";
import schema from "./path/to/schema.json";

const options = { foo: "bar" };

validate(schema, options, {
  name: "MyPlugin",
  postFormatter: (formattedError, error) => {
    if (error.keyword === "type") {
      return `${formattedError}\nAdditional Information.`;
    }

    return formattedError;
  },
});

Invalid options object. MyPlugin has been initialized using an options object that does not match the API schema.
 - options.optionName should be a integer.
   Additional Information.

Examples

schema.json

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

Loader

import schema from "path/to/schema.json";
import { getOptions } from "loader-utils";
import { validate } from "schema-utils";

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

  validate(schema, options, {
    name: "Loader Name",
    baseDataPath: "options",
  });

  // Code...
}

export default loader;

Plugin

import schema from "path/to/schema.json";
import { validate } from "schema-utils";

class Plugin {
  constructor(options) {
    validate(schema, options, {
      name: "Plugin Name",
      baseDataPath: "options",
    });

    this.options = options;
  }

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

export default Plugin;

Precompiled schemas

Compiling a schema at runtime loads ajv, which costs about 150ms for the first schema of a process and a few to tens of milliseconds for every other one. A loader or a plugin can compile its schema ahead of time instead, into a check that validate takes as its fourth argument:

npx schema-utils precompile src/options.json

This writes src/options.check.js next to the schema. Commit it, and publish it with the package:

import { validate } from "schema-utils";
import check from "./options.check.js";
import schema from "./options.json";

validate(schema, options, { name: "Loader Name" }, check);

When the options are valid, the check is all that runs and ajv is never loaded. When they are not, validate runs the full validation to report what is wrong, so the errors are the same as without a check.

Run schema-utils precompile --check src/options.json in CI to fail when the check is missing or out of date with its schema. The generated module may need schema-utils as a dependency of the package. It is an ES module when the nearest package.json has "type": "module", the way Node.js reads a .js file there, and CommonJS otherwise.

With --minify, the check drops the error objects it never reports, has its helpers written into it instead of loaded from schema-utils, and is minified with webpack's own minifier, which needs webpack 5.112.0 or later. For webpack's own options that is less than half the size and loads in 13ms instead of 21ms. --check has to be given the same --minify to compare against the right code.

A relative $ref to another file resolves against the schema. To compile a schema from code, use precompile(schema, { loadSchema, esm, minify }), it returns the source of the module.

Allow to disable and enable validation (the validate function do nothing)

This can be useful when you don't want to do validation for production builds.

import { disableValidation, enableValidation, validate } from "schema-utils";

// Disable validation
disableValidation();
// Do nothing
validate(schema, options);

// Enable validation
enableValidation();
// Will throw an error if schema is not valid
validate(schema, options);

// Allow to undestand do you need validation or not
const need = needValidate();

console.log(need);

Also you can enable/disable validation using the process.env.SKIP_VALIDATION env variable.

Supported values (case insensitive):

• yes/y/true/1/on
• no/n/false/0/off

The variable is read when schema-utils is loaded, so set it before starting the process:

SKIP_VALIDATION=y webpack

Use enableValidation()/disableValidation() to change it while the process is running - they take effect immediately and apply to every copy of schema-utils in the process.

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

The package itself runs on Node.js 10.13.0 and above, but the dev dependencies require an active LTS release, so use one to work on it. CI installs older ones to run the tests on the older versions of Node.js the package supports.

License

MIT