esbuild-ajv

0.0.1 verified Fri May 01 auth: no javascript

esbuild plugin (v0.0.1, pre-1.0.0) to pre-compile Ajv JSON schemas at build time for faster runtime, CSP compliance, and smaller bundles. Pre-compilation avoids dynamic code generation (Function constructor), enabling use in environments with strict `unsafe-eval` CSP. Requires esbuild for building and Ajv v8 for schema compilation. Differentiates from runtime-only Ajv usage by moving compilation overhead to build step.

Common errors

error Cannot find module 'esbuild-ajv' ↓

cause esbuild-ajv not installed or not in node_modules.

fix

Run npm install -D esbuild-ajv ajv.

error Module parse failed: Unexpected token (1:0) - file: .../.ajv.json ↓

cause esbuild-ajv plugin not applied or esbuild cannot handle `.ajv.json` imports without plugin.

fix

Add AjvPlugin() to esbuild plugins array.

error require() of ES Module esbuild-ajv not supported ↓

cause Trying to use `require` with ESM-only package.

fix

Use import AjvPlugin from 'esbuild-ajv' instead of require.

Warnings

breaking Pre-1.0.0 version: API may change without major semver bump. ↓

fix Lock version to exact; review changelog before upgrading.

deprecated Ajv v8 is peer dependency; Ajv v7 is not supported. ↓

fix Ensure project uses `ajv@^8.0.0`.

gotcha Plugin modifies esbuild resolve to treat `.ajv.json` imports specially; non-standard file extension. ↓

fix Use `.ajv.json` extension for schema files to be precompiled.

Install

npm install esbuild-ajv

yarn add esbuild-ajv

pnpm add esbuild-ajv

Imports

AjvPlugin

wrong

const AjvPlugin = require('esbuild-ajv')

correct

import AjvPlugin from 'esbuild-ajv'

Default export; package is ESM-only. Use import statement.

PluginOptions

import AjvPlugin, { PluginOptions } from 'esbuild-ajv'

TypeScript type export for plugin options.

validator

wrong

import validator from './some.ajv.json'

correct

import { validator } from './some.ajv.json'

Precompiled modules export a named export `validator`, not default.

Quickstart

Registers esbuild-ajv plugin in an esbuild build, passing Ajv options and extra keywords.

import esbuild from 'esbuild';
import AjvPlugin from 'esbuild-ajv';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    AjvPlugin({
      extraKeywords: [/* custom keyword definitions */],
      ajvOptions: { coerceTypes: true, useDefaults: true },
    }),
  ],
});