@ata-project/unplugin weekly downloads statistics

@ata-project/unplugin

Compiles JSON Schema files into self-contained ata-validator modules at build time, with TypeScript declarations, in Vite, Webpack, Rollup, Rolldown, esbuild and Rspack. One plugin, built on unplugin.

The generated module imports nothing. A small schema compiles to about 1.3 KB gzipped and a ten-field one to about 2.6 KB, full error detail included, on ata-validator 1.36.0; the module exports validate, isValid and the inferred type, and runs anywhere plain JavaScript runs.

Schemas can be authored as .json, .js or .ts.

It also compiles away new Validator(schema) in your own code wherever the schema is known at build time and the result is the same, so the runtime compiler stays out of the bundle: for the test entry, 122.5 KB gzipped becomes 16.7 KB. See compileAway.

Install

ata-validator is a peer dependency and is only used at build time.

Setup

Vite:

Webpack:

Rollup:

esbuild:

Rspack:

Rolldown:

Next.js uses Webpack, so the Webpack entry goes into next.config.js:

Turbopack has no plugin interface this could attach to. Run the compile as a step before the build instead: ata build 'schemas/**/*.schema.json' from ata-validator's CLI, or the compile() function below in a script.

The .schema.json convention

Name a schema user.schema.json and import a typed validator by its name:

The plugin writes user.schema.js and user.schema.d.ts next to the schema. The default export is the validate function; validate, isValid and the inferred type are also named exports. The type name comes from the schema's title, then its $id, then the file name.

Add the generated files to .gitignore:

Other sources (.json without the .schema suffix, .js, .ts) produce .validator.mjs and .validator.d.mts.

Options

| Option | Default | Description |

| schemas | **/*.schema.json | Glob or globs, relative to the root. node_modules is skipped. | | outDir | next to each schema | Directory for generated files, mirroring the source layout. | | format | 'esm' | 'esm' or 'cjs'. | | abortEarly | false | Emit the smaller validator that stops at the first failure. | | types | true | Emit a .d.ts next to each validator. | | nameFromFile | file name in PascalCase | Type name for schemas without title or $id. | | root | from the bundler | Where the globs resolve from. Vite's root, Webpack's and Rspack's context and esbuild's absWorkingDir are read; Rollup and Rolldown need it passed. | | alias | Vite's resolve.alias | Import aliases inside .ts schema files. tsconfig paths work without configuration. | | compileAway | true | Replace new Validator(schema) in your code with a validator compiled at build time, where that gives the same results. See below. Needs ata-validator 1.36.0; with an older version the runtime stays, and a warning is printed only if you set the option yourself. | | sharedErrors | 'auto' | Where a compiled validator's error detail comes from. A compact module carries its verdict and its schema and takes its errors from ata-validator/error-runtime, which the bundle holds once. 'auto' scans the project's sources at build start (skipping node_modules, build output and test files), adds up what every replaceable call would save, and uses the runtime when the total pays for it; a file the scan did not see decides alone, which takes a schema of several hundred properties. Measured on projects of 1 to 40 SchemaStore schemas, no bundle came out bigger than with false, and 40 schemas went from 724 KB to 405 KB gzipped, on ata-validator 1.51.0. true writes every schema that allows it compact, and false never. The scan adds little to the build, measured in separate processes with esbuild: 84 to 85 ms for three validators, 681 to 715 ms for forty. Errors and verdicts are the same either way; a rejected document costs more, since its errors come from an interpreted walk. Needs ata-validator 1.50.0; with an older one every module stays self-contained, as before. |

compileAway: keep new Validator, drop the compiler

Code written against the runtime API is compiled at build time without being changed. This is on by default; compileAway: false turns it off.

The plugin puts a compiled validator in place of the new Validator(...) call, and once nothing else in the file uses the ata-validator import, the import goes with it, so the runtime compiler is not in the bundle. For the three-schema entry in test/fixtures/compile-away, one of them with defaults, a minified Vite library build is 122.5 KB gzipped without it and 16.7 KB with it (gzip level 9), on ata-validator 1.39.2. Across the 977 schemas of SchemaStore, 725 can be compiled away this way.

Where the code only ever calls isValidObject() or isValidJSON(), the plugin uses a smaller wrapper without the error machinery (needs ata-validator 1.40.0): a small app that only asks for a boolean bundles to 2.6 KB gzipped, against 12.1 KB with the full wrapper and 102.0 KB for the runtime, on 0.5.0 with ata-validator 1.40.0.

The replacement answers validate(), isValidObject(), validateJSON() and isValidJSON() as a Validator with default options does: the same verdicts, defaults filled in, data on success, and the same errors, enriched the same way, since they come from the same code in ata-validator. ata-validator's own tests hold that over every case of the official JSON Schema test suite and over seeded schemas with defaults at every depth.

A call is replaced only when all of this is true, and left to the runtime otherwise:…

Description from the npm listing.