Valibot — Modular Schema Validation for TypeScript

Introduction

Valibot is a schema validation library for TypeScript created by Fabian Hiller. Its key innovation is a modular, tree-shakable API design: instead of chaining methods on a class, each validation function is a standalone import. This means bundlers can eliminate unused code, producing validation bundles that are a fraction of the size of traditional libraries like Zod.

What Valibot Does

• Validates data against schemas with full TypeScript type inference
• Produces minimal bundle sizes through function-level tree shaking
• Supports objects, arrays, unions, intersections, tuples, and recursive types
• Provides transformations (coercion, defaults, mapping) within the schema pipeline
• Works in Node.js, Deno, Bun, browsers, and edge runtimes

Architecture Overview

Valibot uses a pipe-based composition model. A schema is defined with a base type function (e.g., v.string()) and refined through v.pipe() which chains validation actions (v.minLength, v.email) and transformations. Each function is a separate ES module export, so bundlers tree-shake everything not explicitly imported. The parse step walks the pipe sequentially, collecting issues into a typed error array on failure or returning the validated and transformed value on success.

Self-Hosting & Configuration

• Install via npm, pnpm, or yarn—no peer dependencies required
• Zero configuration needed—import and use directly in any TypeScript project
• Works with any bundler (Vite, Webpack, esbuild, Rollup) for tree shaking
• Integrates with form libraries via @valibot/to-json-schema for JSON Schema export
• Adapters available for React Hook Form, TanStack Form, and SvelteKit

Key Features

• Bundle size under 1 KB for common schemas vs. 12+ KB for equivalent Zod schemas
• Full TypeScript type inference with v.InferOutput<typeof schema> helper
• Pipe-based composition for chaining validations and transformations
• Async validation support for database lookups and API checks
• Internationalization-ready error messages with custom error functions

Comparison with Similar Tools

• Zod — method-chaining API with larger bundle; Valibot is modular with 98% smaller bundles
• Yup — older library with mutable schema builders; Valibot is immutable and tree-shakable
• AJV — JSON Schema-based validator; Valibot uses TypeScript-native schemas with better DX
• io-ts — fp-ts-based codecs; Valibot is simpler with no functional programming prerequisites
• Effect Schema — part of the Effect ecosystem; Valibot is standalone with minimal API surface

FAQ

Q: Should I use Valibot or Zod? A: If bundle size matters (client-side validation, edge functions), Valibot's modular design produces much smaller bundles. If you prefer method chaining and a larger ecosystem, Zod is well-established.

Q: Does Valibot work with React Hook Form? A: Yes. Use the @valibot/resolver package with React Hook Form for schema-based form validation.

Q: Can I generate JSON Schema from Valibot schemas? A: Yes. The @valibot/to-json-schema package converts Valibot schemas to JSON Schema for OpenAPI or other uses.

Q: How does Valibot handle optional and nullable fields? A: Use v.optional() for fields that may be undefined and v.nullable() for null values. They compose naturally with other schema types.

Sources

• https://github.com/fabian-hiller/valibot
• https://valibot.dev