Getting Started with Valibot

Mar 22, 2026 · 3 min read

TypeScript gives you compile-time type safety, but it can’t protect you at runtime. When data arrives from a form submission, an API response, or a configuration file, TypeScript’s types are already gone. That’s the gap schema validation libraries fill — and it’s exactly where Valibot shines.

This guide walks you through what Valibot is, how it works, and how to start using it for TypeScript schema validation in real frontend projects.

Key Takeaways

Valibot is a modular, TypeScript-first schema validation library that validates data at runtime and infers static types from your schemas.
Its tree-shakeable architecture keeps bundle sizes minimal — often around ~1 KB when tree-shaken — making it ideal for frontend applications.
The pipe function enables composable validation pipelines with clear, field-level error messages.
Valibot integrates well with popular form libraries and supports JSON Schema output via a companion package for API documentation.

What Is Valibot and Why Use It?

Valibot is a modular, TypeScript-first schema validation library. It validates unknown data at runtime and infers static TypeScript types from your schemas, so your schema becomes the single source of truth for both runtime safety and compile-time types.

What makes it stand out is its architecture. Instead of one large object with chained methods (the approach Zod takes), Valibot is built from many small, independent functions. Bundlers can tree-shake anything you don’t use, which keeps your production bundle minimal — often around ~1 KB depending on usage. That’s a meaningful advantage in frontend applications where bundle size directly affects load time.

Valibot is stable, actively maintained, and at v1+, making it a solid choice for production use.

Defining Your First Valibot Schema

Defining a schema in Valibot looks similar to writing a TypeScript type, but it runs at runtime:

import * as v from 'valibot'

const LoginSchema = v.object({
  email: v.string(),
  password: v.string(),
})

You can then derive a TypeScript type directly from the schema:

type LoginData = v.InferOutput<typeof LoginSchema>
// { email: string; password: string }

No duplication. Your schema and your type stay in sync automatically.

Parsing and Validating Data

Valibot gives you two main ways to validate data.

parse throws an error if validation fails:

const data = v.parse(LoginSchema, { email: 'jane@example.com', password: '12345678' })

safeParse returns a result object instead of throwing, which is useful when you want to handle errors without try/catch:

const result = v.safeParse(LoginSchema, { email: '', password: '' })

if (!result.success) {
  console.log(result.issues) // Structured error details
}

For form validation, safeParse is usually the better choice — it keeps error handling clean and predictable.

Composable Validation Pipelines

Valibot’s pipe function lets you chain validation and transformation steps. A pipeline always starts with a base schema, followed by actions that run in sequence:

const EmailSchema = v.pipe(
  v.string('Email must be a string.'),
  v.nonEmpty('Please enter your email.'),
  v.email('Invalid email format.')
)

Each action receives the output of the previous one. This makes it straightforward to enforce rules like minimum length, specific formats, or custom constraints — all with clear, field-level error messages that you control.

Valibot vs Zod: The Key Difference

Both libraries solve the same core problem. The practical difference is in design philosophy and bundle impact.

Feature	Valibot	Zod
Bundle size	~1 KB+ (tree-shaken)	~10–15 KB
Tree-shakeable	✅ Full	⚠️ Partial
API style	Functional, composable	Method chaining
TypeScript inference	✅	✅

If you’re already using Zod, migration is straightforward — the concepts map closely, and the Valibot docs include guidance for developers making the switch.

Ecosystem and What Comes Next

Valibot integrates well with popular form libraries. The Superforms library for SvelteKit has first-class Valibot support, and adapters exist for React Hook Form and other tools.

For teams needing JSON Schema output — for API documentation or OpenAPI specs — the separate @valibot/to-json-schema package handles that. Internationalization for error messages is also supported via @valibot/i18n, making Valibot practical for multilingual applications.

Conclusion

Valibot gives you runtime type safety, clean TypeScript inference, and a minimal footprint — without the overhead of heavier alternatives. Install it, define a schema, and let your validation logic become the foundation your types are built on.

npm install valibot

From there, your schemas can grow with your application — from simple string checks to complex nested objects — without ever bloating your bundle.

FAQs

Yes. Valibot supports nested objects using v.object inside another v.object, and arrays using v.array. You can combine these with pipe to add constraints at any level of depth, and the inferred TypeScript type will reflect the full nested structure automatically.

Absolutely. Valibot runs in any JavaScript environment, so it works on both the client and the server. You can use it to validate form submissions in server actions, API route handlers, or middleware. Its small size makes it especially well-suited for edge runtimes with strict bundle limits.

You can use the v.check action inside a pipe to define custom logic. It accepts a function that returns true or false, along with an error message. For transformations, v.transform lets you modify the validated output. Both integrate seamlessly into any validation pipeline.

Not particularly. The core concepts like schemas, parsing, and type inference map closely between the two libraries. The main shift is moving from method chaining to a functional style with standalone functions. The Valibot documentation provides migration guidance to help streamline the process.

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.