How does the pipe() function work in Valibot?

The pipe() function takes a base schema as its first argument and any number of validation or transformation actions as subsequent arguments. It executes them strictly sequentially from left to right, passing the return value of each step as the input to the next.

What is the difference between v.InferInput and v.InferOutput ?

InferInput extracts the TypeScript type expected by the schema before any transformations occur. InferOutput extracts the type produced after all transformation actions (such as v.trim() or v.transform()) in the pipeline have completed.

What is the key distinction between v.parse() and v.safeParse()?

v.parse() returns validated data directly but throws a ValiError exception if validation fails, requiring try/catch handling. v.safeParse() never throws; it returns a discriminated union { success: true, output } or { success: false, issues }.

How do you implement custom validation rules in Valibot without external dependencies?

Use v.check((value) => boolean, errorMessage). If the predicate returns false, Valibot registers an issue with the provided message. For lower-level control over issues and path manipulation, v.rawCheck() is used.

Does Valibot support asynchronous validation checks?

Yes. Valibot provides dedicated asynchronous counterparts: v.parseAsync(), v.safeParseAsync(), and asynchronous schema/action utilities such as v.checkAsync and v.rawCheckAsync for operations like database uniqueness lookups.

Why does Zod fail to tree-shake effectively while Valibot excels at it?

Zod employs an object-oriented fluent chaining model where all validation methods (min, max, email) reside on class prototypes like ZodString. Module bundlers (Rollup, Webpack) cannot strip class prototype methods because they are statically attached to the class object. Valibot is composed of standalone pure functions, enabling the bundler to retain only the specific functions explicitly imported in your code.

How do you associate an object-level validation error with a specific field in Valibot?

Using the v.forward(action, path) utility. It accepts a validation action (such as a v.check comparing password and confirmPassword) along with an array representing the target field path (e.g., ['confirmPassword']), directing the issue to that specific field in the error map.

What is the typical bundle size reduction when replacing Zod with Valibot in a client form?

For a typical 4–5 field form, Zod adds ~14 KB (gzipped) to the client bundle. The equivalent Valibot schema with tree-shaking adds only 800 bytes to 1.5 KB (gzipped), resulting in a 90–95% reduction in validation code weight.

Valibot: Modular Validation, Tree-Shaking, and Schema Pipelines — TypeScript 5.8+ Mastery

Architectural Foundation#

In client-side web applications (Next.js Client Components, SPAs, micro-frontends), JavaScript bundle weight directly dictates Core Web Vitals performance metrics: specifically Total Blocking Time (TBT) and Interaction to Next Paint (INP). The larger the downloaded script payloads, the longer mobile CPUs spend parsing and compiling JavaScript inside V8, freezing the browser's main UI thread.

Historically, the ecosystem's dominant library—Zod—was engineered around an object-oriented, fluent method-chaining model:

typescript

z.string().min(5).max(100).email().trim();

Under this class-based architecture, every conceivable validation and transformation method is hardwired directly into the prototype of ZodString and its base class ZodType. Modern bundler Tree-Shaking algorithms (Rollup, Webpack, Turbopack, Vite) analyze static import graphs at the ES module level. Because class methods are bound to a single monolithic object, the bundler cannot determine which prototype methods are used and which are dead code. Consequently, importing a single primitive like z.string() pulls the entire monolithic Zod library (approx. 55–70 KB uncompressed / ~14 KB gzipped) into the client bundle.

Valibot resolves this architectural bottleneck through pure functional decomposition. In Valibot, monolithic classes are eliminated. Every primitive schema (string, number), every validator (email, minLength, regex), and every transformation (trim, toLowerCase) is an isolated, independently exported higher-order function.

The foundational bridge is the pipe() pipeline, which composes a base schema with a sequence of validation and transformation Actions. The bundler bundles only the functions explicitly imported by the application, slashing client-side validation payloads down to under 1 KB (gzip) (a 90–95% size reduction).

Mental Model#

Contrasting an OOP method chain against modular functional composition illustrates how tree-shaking operates:

text

+-------------------------------------------------------------------------+
|                  ZOD MONOLITHIC GRAPH (Tree-Shaking Impossible)         |
+-------------------------------------------------------------------------+
|  import { z } from 'zod';                                               |
|  z.string().email();                                                    |
|                                                                         |
|  Bundler inspects the ZodString class:                                  |
|  class ZodString {                                                      |
|    min() { ... }     // <- Retained in bundle even if never called!     |
|    max() { ... }     // <- Retained in bundle!                          |
|    uuid() { ... }    // <- Retained in bundle!                          |
|    regex() { ... }   // <- Retained in bundle!                          |
|    ip() { ... }      // <- Retained in bundle!                          |
|  }                                                                      |
|  => Total bundle footprint: ~14 KB (gzip)                               |
+-------------------------------------------------------------------------+
|                                                                         |
|                  VALIBOT MODULAR GRAPH (Full Tree-Shaking)              |
+-------------------------------------------------------------------------+
|  import { object, string, email, pipe } from 'valibot';                 |
|                                                                         |
|  Bundler analyzes exported ES symbols:                                  |
|  - object()   => Bundled (~350 bytes)                                   |
|  - string()   => Bundled (~150 bytes)                                   |
|  - email()    => Bundled (~200 bytes)                                   |
|  - pipe()     => Bundled (~100 bytes)                                   |
|  * All other 150+ library exports are completely purged from build!     |
|  => Total bundle footprint: ~850 bytes (gzip)!                          |
+-------------------------------------------------------------------------+

Dead Code Elimination (Tree-Shaking)
Functional Decomposition
Validation Pipeline (pipe)
Validation Action

Practical Applications#

Client authentication forms in Next.js App Router: Keeping login and registration page chunks between 5–10 KB to achieve maximum Lighthouse performance scores.
Embeddable lightweight widgets and SDKs: Chatbots, payment modals, and feedback tools where minimal host page impact is a strict non-negotiable SLA.
Low-bandwidth mobile web apps (3G/LTE): Drastically cutting Total Blocking Time (TBT) on mid-tier mobile devices by avoiding parsing unused library bytecode.
Serverless & Edge Compute (Cloudflare Workers): Minimizing cold-boot spin-up times for isolated worker runtimes through tiny bundle footprints.

How It Works#

1. The Valibot Pipeline Architecture#

Architecture Pipeline

Data Processing Pipeline in pipe()

4 stages

1. Base Schema Validation

Type GateCore / System

The initial argument of pipe() checks the primitive type (string, number, object). If mismatched, the pipeline aborts immediately.

Artifacts:string()number()BaseSchema

2. Sequential Action Processing

Action LoopCore / System

Data flows linearly through transformations (trim, toLowerCase) and constraint checkers (minLength, email).

Artifacts:trim()minLength(5)email()

3. Issue Tracking and Collection

Error CollectionCore / System

Upon failure, actions emit detailed SchemaIssue structures with precise path tracking and localized messages.

Artifacts:SchemaIssueIssuePath

4. Typed Result Synthesis

Output SynthesisCore / System

safeParse returns a discriminated union: { success: true, output } or { success: false, issues }.

Artifacts:SafeParseResultInferOutput<TSchema>

2. Schema Composition Syntax: Comparing Zod and Valibot#

Let us implement user profile validation using Valibot:

typescriptsrc/valibot/profile-schema.ts

import * as v from 'valibot';

// Constructing a schema via functional composition with pipe()
export const UserProfileSchema = v.object({
  id: v.pipe(
    v.string(),
    v.uuid('Identifier must be a valid UUID v4')
  ),
  username: v.pipe(
    v.string(),
    v.trim(), // Transformation: strip whitespace
    v.minLength(3, 'Username must be at least 3 characters'),
    v.maxLength(20, 'Username must not exceed 20 characters')
  ),
  email: v.pipe(
    v.string(),
    v.trim(),
    v.toLowerCase(), // Transformation: normalize casing
    v.email('Invalid email address format')
  ),
  age: v.pipe(
    v.number(),
    v.minValue(18, 'Service is restricted to users 18 and older'),
    v.maxValue(100, 'Please enter a valid age')
  ),
  website: v.optional(
    v.pipe(
      v.string(),
      v.url('Invalid URL format')
    )
  ),
});

// Static inference of incoming raw data (pre-transformations)
export type UserProfileInput = v.InferInput<typeof UserProfileSchema>;

// Static inference of processed data (post-trim and post-toLowerCase)
export type UserProfileOutput = v.InferOutput<typeof UserProfileSchema>;

[!NOTE] Note the explicit separation between InferInput and InferOutput. Because the pipeline includes transformations (trim(), toLowerCase()), the shape of the raw input can differ from the validated output, which TypeScript tracks with complete type safety.

3. Implementing Custom Validation Actions#

Valibot enables writing custom validators without library bloat using check or lower-level rawCheck:

typescriptsrc/valibot/custom-validators.ts

import * as v from 'valibot';

// Custom password strength validator action
export function passwordStrength(requirementMessage = 'Password must contain at least 1 number and 1 special symbol') {
  return v.check((input: string) => {
    const hasNumber = /\d/.test(input);
    const hasSpecialChar = /[!@#$%^&*(),.?":{}|<>]/.test(input);
    return hasNumber && hasSpecialChar;
  }, requirementMessage);
}

// Custom VAT/Tax ID checksum validation action (e.g., 10-digit number with checksum)
export function isValidTaxId(errorMessage = 'Invalid enterprise tax identifier format') {
  return v.check((input: string) => {
    if (!/^\d{10}$/.test(input)) return false;
    
    const coefficients = [2, 4, 10, 3, 5, 9, 4, 6, 8];
    const controlSum = coefficients.reduce(
      (sum, coeff, idx) => sum + coeff * Number(input[idx]),
      0
    );
    const controlDigit = (controlSum % 11) % 10;
    
    return Number(input[9]) === controlDigit;
  }, errorMessage);
}

// Using custom actions inside a schema pipeline
export const SecurityFormSchema = v.object({
  taxId: v.pipe(
    v.string(),
    v.trim(),
    isValidTaxId()
  ),
  password: v.pipe(
    v.string(),
    v.minLength(8, 'Password must be at least 8 characters long'),
    passwordStrength()
  ),
});

4. Safe UI Form Parsing Architecture#

In client-side forms, always employ safeParse to prevent uncaught runtime exceptions:

typescriptsrc/valibot/form-handler.ts

import * as v from 'valibot';
import { UserProfileSchema, UserProfileOutput } from './profile-schema';

export interface FormSubmissionResult {
  isSuccess: boolean;
  data?: UserProfileOutput;
  fieldErrors?: Record<string, string>;
}

export function handleProfileSubmission(rawFormData: unknown): FormSubmissionResult {
  // safeParse returns a typed outcome object without throwing exceptions
  const result = v.safeParse(UserProfileSchema, rawFormData);

  if (!result.success) {
    // Transform flat issues array into a field-keyed error dictionary
    const fieldErrors: Record<string, string> = {};

    for (const issue of result.issues) {
      // Extract first path segment name (e.g., 'email' or 'username')
      const fieldName = issue.path?.[0]?.key;
      if (typeof fieldName === 'string' && !fieldErrors[fieldName]) {
        fieldErrors[fieldName] = issue.message;
      }
    }

    return {
      isSuccess: false,
      fieldErrors,
    };
  }

  // Data is fully verified and transformed
  return {
    isSuccess: true,
    data: result.output,
  };
}

Comparative Architecture and Bundle Metrics#

Client Bundle Validation Metrics

Критерий	Zod (Monolithic Architecture)	Valibot (Modular Architecture)
Bundle Impact (1 standard form)	~55 KB (Unminified) / ~14 KB (Gzip)	0.8 – 1.5 KB (Gzip) (over 90% reduction)
Tree-Shaking Support	Non-viable: Methods are bound to ZodType class prototypes	Full: Bundlers shake out all unused functions
Architectural Paradigm	OOP Fluent Method Chaining (z.string().min())	Functional Pipeline Composition (pipe(string(), minLength()))
Input / Output Separation	Implicit (z.input<T> and z.output<T>)	Strict type segregation (InferInput<T> and InferOutput<T>)

Production Artifact: Production-Grade Registration Validation Module#

Here is an architectural module featuring domain validators for authentication workflows:

Production Artifactsrc/valibot/AuthValidationModule.ts

A lightweight registration and login validation module built on Valibot with zero unnecessary client bundle overhead.

typescript

import * as v from 'valibot';

// 1. Reusable primitive building blocks
export const EmailSchema = v.pipe(
  v.string(),
  v.trim(),
  v.toLowerCase(),
  v.email('Invalid corporate email syntax'),
  v.maxLength(100, 'Email must not exceed 100 characters')
);

export const PasswordSchema = v.pipe(
  v.string(),
  v.minLength(8, 'Password must be at least 8 characters long'),
  v.maxLength(64, 'Password must not exceed 64 characters')
);

// 2. Login schema
export const LoginSchema = v.object({
  email: EmailSchema,
  password: PasswordSchema,
  rememberMe: v.optional(v.boolean(), false),
});

// 3. Registration schema with password confirmation matching via forward/check
export const RegistrationSchema = v.pipe(
  v.object({
    email: EmailSchema,
    password: PasswordSchema,
    confirmPassword: v.string(),
    agreeToTerms: v.pipe(
      v.boolean(),
      v.check((val) => val === true, 'You must accept the terms of service')
    ),
  }),
  // Cross-field comparison at object level
  v.forward(
    v.check(
      (input) => input.password === input.confirmPassword,
      'Passwords do not match'
    ),
    ['confirmPassword'] // Associates the error with the confirmPassword field
  )
);

export type LoginCredentials = v.InferOutput<typeof LoginSchema>;
export type RegistrationPayload = v.InferOutput<typeof RegistrationSchema>;

Common Pitfalls#

Ошибка: Attempting OOP method chaining familiar from Zod

Developers transitioning from Zod often intuitively write v.string().min(5) or v.object().required(). This triggers a runtime TypeError: v.string(...).min is not a function, because v.string() returns a simple schema descriptor object without prototype methods. All validation rules must be composed inside v.pipe().

typescript

// ❌ BROKEN: Attempting class method chaining
const BrokenSchema = v.string().minLength(5); // TypeError!

// ✅ RECOMMENDED: Functional composition via pipe()
const CorrectSchema = v.pipe(v.string(), v.minLength(5));

Ошибка: Incorrect action sequencing inside pipe()

pipe() executes actions strictly from left to right. Placing an email() validator before a trim() action means a string like " [email protected] " will be rejected by the regex validator due to leading whitespace before trim() has a chance to sanitize it. Data sanitization actions must always precede format validations.

typescript

// ❌ WRONG: email() fails due to spaces before trim() executes
const BadOrder = v.pipe(v.string(), v.email(), v.trim());

// ✅ RECOMMENDED: Sanitize data first, then validate
const GoodOrder = v.pipe(v.string(), v.trim(), v.email());

Ошибка: Invoking v.parse() directly in UI handlers without try/catch

The v.parse() method throws a heavy ValiError exception on validation failure. Calling it inside client form event listeners without try/catch crashes the component render tree and presents users with an unhandled error screen. In client form code, always use v.safeParse().

Ошибка: Using wildcard imports without proper bundler configuration

While import * as v from 'valibot' is tree-shakeable in properly configured modern bundlers, importing unused utilities into client chunks risks accidental inclusion of extra polyfills. Prefer explicit named imports: import { object, string, pipe } from 'valibot'.

Step-by-Step Data Flow in pipe()#

Action Processing Cycle in pipe()

Base Schema Evaluation

Checks the root primitive type (string, number, boolean). If invalid, execution halts immediately.

First Action Execution

Input passes to the initial action (e.g., trim() normalization), which yields a sanitized string.

Validation Check Evaluation

Sanitized data flows through assertions (minLength, email). Failures append to an issues collection.

Output Synthesis

If issues is empty, safeParse yields a success status with the finalized output payload.

Interview Questions & Deep Dives#

Interview Questions8 questions

Valibot: Modular Validation, Tree-Shaking, and Schema Pipelines

Architectural Foundation#

Mental Model#

Practical Applications#

How It Works#

1. The Valibot Pipeline Architecture#

Data Processing Pipeline in pipe()

1. Base Schema Validation

2. Sequential Action Processing

3. Issue Tracking and Collection

4. Typed Result Synthesis

2. Schema Composition Syntax: Comparing Zod and Valibot#

3. Implementing Custom Validation Actions#

4. Safe UI Form Parsing Architecture#

Comparative Architecture and Bundle Metrics#

Production Artifact: Production-Grade Registration Validation Module#

Common Pitfalls#

Ошибка: Attempting OOP method chaining familiar from Zod

Ошибка: Incorrect action sequencing inside pipe()

Ошибка: Invoking v.parse() directly in UI handlers without try/catch

Ошибка: Using wildcard imports without proper bundler configuration

Step-by-Step Data Flow in pipe()#

Interview Questions & Deep Dives#

Related Topics#

Architectural Foundation#

Mental Model#

Practical Applications#

How It Works#

1. The Valibot Pipeline Architecture#

Data Processing Pipeline in pipe()

1. Base Schema Validation

2. Sequential Action Processing

3. Issue Tracking and Collection

4. Typed Result Synthesis

2. Schema Composition Syntax: Comparing Zod and Valibot#

3. Implementing Custom Validation Actions#

4. Safe UI Form Parsing Architecture#

Comparative Architecture and Bundle Metrics#

Production Artifact: Production-Grade Registration Validation Module#

Common Pitfalls#

Ошибка: Attempting OOP method chaining familiar from Zod

Ошибка: Incorrect action sequencing inside pipe()

Ошибка: Invoking v.parse() directly in UI handlers without try/catch

Ошибка: Using wildcard imports without proper bundler configuration

Step-by-Step Data Flow in pipe()#

Interview Questions & Deep Dives#

Related Topics#