@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

npm install --save-dev @ata-project/unplugin ata-validator

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

Setup

Vite:

// vite.config.ts
import ata from '@ata-project/unplugin/vite'

export default {
  plugins: [ata({ schemas: 'src/**/*.schema.json' })],
}

Webpack:

// webpack.config.js
const ata = require('@ata-project/unplugin/webpack')

module.exports = {
  plugins: [ata({ schemas: 'src/**/*.schema.json' })],
}

Rollup:

// rollup.config.js
import ata from '@ata-project/unplugin/rollup'

export default {
  // Rollup has no project root; tell the plugin where the globs start.
  plugins: [ata({ schemas: 'src/**/*.schema.json', root: process.cwd() })],
}

esbuild:

import { build } from 'esbuild'
import ata from '@ata-project/unplugin/esbuild'

await build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  plugins: [ata({ schemas: 'src/**/*.schema.json' })],
})

Rspack:

// rspack.config.js
const ata = require('@ata-project/unplugin/rspack')

module.exports = {
  plugins: [ata({ schemas: 'src/**/*.schema.json' })],
}

Rolldown:

// rolldown.config.js
import ata from '@ata-project/unplugin/rolldown'

export default {
  plugins: [ata({ schemas: 'src/**/*.schema.json', root: process.cwd() })],
}

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

const ata = require('@ata-project/unplugin/webpack')

module.exports = {
  webpack(config) {
    config.plugins.push(ata({ schemas: 'schemas/**/*.schema.json' }))
    return config
  },
}

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:

import validate, { type User, isValid } from './user.schema'

const r = validate(input)
if (r.valid) {
  // input matched the schema
}
if (isValid(input)) {
  input.id // narrowed to User
}

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:

*.schema.js
*.schema.d.ts

Other sources (.json without the .schema suffix, .js, .ts) produce <name>.validator.mjs and <name>.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…