valibot

The modular and type safe schema library for validating structural data

weekly downloads5.6M

versionv1.2.0

licenseMIT

categoryvalidation

modulartypescriptschemavalidationparsingbundle-sizetype-saferuntime

Overview

Valibot is a TypeScript-first schema validation library designed to validate unknown data at runtime while providing compile-time type safety. Unlike traditional validation libraries that use class-based architectures, Valibot exports individual validation functions that can be tree-shaken by modern bundlers, resulting in dramatically smaller production bundles—often 10x smaller than alternatives like Zod.

The library was created to address the bundle size problem inherent in monolithic validation libraries. With over 5.5 million weekly downloads, Valibot has gained traction among developers building performance-critical applications where every kilobyte matters. Its modular architecture means you only pay for what you use: basic schemas start at under 700 bytes minified and gzipped, with individual validation functions as small as 106 bytes.

Valibot provides automatic TypeScript type inference from schemas, eliminating the need to manually maintain separate validation logic and type definitions. This makes it particularly valuable in full-stack TypeScript applications where the same schema can validate data on both client and server. The library offers multiple validation APIs including exception-based parsing, safe parsing that returns results, and type guard functions, giving developers flexibility in error handling patterns.

With 100% test coverage, zero external dependencies, and an MIT license, Valibot serves as both a standalone validation solution and a foundation for building higher-level abstractions like ORMs and API documentation generators through its metadata system.

Quick Start

typescript

import * as v from 'valibot';

// Define a user registration schema
const UserSchema = v.object({
  email: v.pipe(
    v.string(),
    v.email('Invalid email address'),
    v.maxLength(255, 'Email too long')
  ),
  password: v.pipe(
    v.string(),
    v.minLength(8, 'Password must be at least 8 characters'),
    v.regex(/[A-Z]/, 'Must contain uppercase letter'),
    v.regex(/[0-9]/, 'Must contain a number')
  ),
  age: v.pipe(
    v.number(),
    v.minValue(18, 'Must be 18 or older'),
    v.maxValue(120, 'Invalid age')
  ),
  role: v.optional(v.picklist(['user', 'admin', 'moderator']), 'user')
});

// Infer TypeScript type from schema
type User = v.InferOutput<typeof UserSchema>;

// Safe parsing (no exceptions)
const result = v.safeParse(UserSchema, {
  email: 'user@example.com',
  password: 'Secret123',
  age: 25
});

if (result.success) {
  const user: User = result.output;
  console.log('Valid user:', user);
  // Output includes default role: 'user'
} else {
  console.error('Validation errors:', result.issues);
}

// Exception-based parsing for cleaner code when errors should throw
try {
  const user = v.parse(UserSchema, formData);
  await saveToDatabase(user);
} catch (error) {
  if (error instanceof v.ValiError) {
    return { errors: error.issues };
  }
  throw error;
}

Use Cases

Form validation in modern web frameworks: Use identical schemas in Next.js, Remix, or Nuxt applications to validate form data on both client and server, ensuring consistent validation logic without code duplication while minimizing client-side JavaScript overhead.

API request validation with zero-trust architecture: Validate incoming HTTP requests on edge functions or serverless endpoints where cold start times and bundle sizes directly impact response latency and costs, rejecting malformed data before it reaches business logic.

Environment variable and configuration validation: Parse and validate environment variables or configuration files at application startup with detailed error messages, catching misconfiguration issues before they cause runtime failures in production.

JSON Schema generation for LLM structured outputs: Convert Valibot schemas to JSON Schema for constraining large language model responses in AI applications, or generate OpenAPI specifications for automatic API documentation.

Building type-safe ORMs and data layers: Leverage Valibot's metadata system to create database schemas with custom annotations for primary keys, indexes, and relationships, using validation schemas as the single source of truth for both runtime validation and database structure.

Pros & Cons

Pros

+Exceptional bundle size efficiency with tree-shaking support reduces production builds by up to 98% compared to Zod, improving load times and SEO metrics
+Full TypeScript type inference eliminates manual type definitions and keeps validation logic synchronized with types automatically
+Modular architecture allows extending functionality without bloating bundle sizes for users who don't need advanced features
+Multiple validation APIs (parse, safeParse, is) provide flexibility for different error handling patterns and use cases
+Zero dependencies and 100% test coverage reduce supply chain risks and ensure reliability

Cons

−Smaller ecosystem and fewer third-party integrations compared to more established alternatives like Zod or Yup
−Function-based API requires more imports compared to chained method syntax, which some developers find less ergonomic
−Relatively newer library (v1 released recently) means less community knowledge, Stack Overflow answers, and production battle-testing

Alternatives

joiv18.0.2

Object schema validation

validationschemavalidation

15.5M / week

yupv1.7.1

Dead simple Object schema validation

validation

9.0M / week

zodv4.3.6

TypeScript-first schema declaration and validation library with static type inference

validationtypescriptschema

85.3M / week

Comparisons

valibot vs superstruct

validation

Install

bash

npm install valibot

bash

pnpm add valibot

bash

bun add valibot

Overview

Quick Start

typescript

import * as v from 'valibot';

// Define a user registration schema
const UserSchema = v.object({
  email: v.pipe(
    v.string(),
    v.email('Invalid email address'),
    v.maxLength(255, 'Email too long')
  ),
  password: v.pipe(
    v.string(),
    v.minLength(8, 'Password must be at least 8 characters'),
    v.regex(/[A-Z]/, 'Must contain uppercase letter'),
    v.regex(/[0-9]/, 'Must contain a number')
  ),
  age: v.pipe(
    v.number(),
    v.minValue(18, 'Must be 18 or older'),
    v.maxValue(120, 'Invalid age')
  ),
  role: v.optional(v.picklist(['user', 'admin', 'moderator']), 'user')
});

// Infer TypeScript type from schema
type User = v.InferOutput<typeof UserSchema>;

// Safe parsing (no exceptions)
const result = v.safeParse(UserSchema, {
  email: 'user@example.com',
  password: 'Secret123',
  age: 25
});

if (result.success) {
  const user: User = result.output;
  console.log('Valid user:', user);
  // Output includes default role: 'user'
} else {
  console.error('Validation errors:', result.issues);
}

// Exception-based parsing for cleaner code when errors should throw
try {
  const user = v.parse(UserSchema, formData);
  await saveToDatabase(user);
} catch (error) {
  if (error instanceof v.ValiError) {
    return { errors: error.issues };
  }
  throw error;
}

Use Cases

Pros & Cons

Pros

+Exceptional bundle size efficiency with tree-shaking support reduces production builds by up to 98% compared to Zod, improving load times and SEO metrics
+Full TypeScript type inference eliminates manual type definitions and keeps validation logic synchronized with types automatically
+Modular architecture allows extending functionality without bloating bundle sizes for users who don't need advanced features
+Multiple validation APIs (parse, safeParse, is) provide flexibility for different error handling patterns and use cases
+Zero dependencies and 100% test coverage reduce supply chain risks and ensure reliability

Cons

−Smaller ecosystem and fewer third-party integrations compared to more established alternatives like Zod or Yup
−Function-based API requires more imports compared to chained method syntax, which some developers find less ergonomic
−Relatively newer library (v1 released recently) means less community knowledge, Stack Overflow answers, and production battle-testing