Valibot: a modular TypeScript schema library with a small bundle footprint

What Valibot validates, and who ends up using it

Valibot is a schema library for structural data. The README frames the problem plainly: incoming data on a server, a form submission, or configuration files. All three are cases where a TypeScript type exists on paper but nothing checks the value at runtime, because TypeScript types are erased before execution. A schema in Valibot is a value that survives compilation. It describes the shape, and it can be executed against unknown input, so the inferred type and the runtime guarantee come from one source instead of two that drift apart.

The intended audience is TypeScript developers who already accept runtime validation as necessary and are choosing a library. The topic list on the repository points at the same use cases: form validation, parsing, runtime validation, type inference. If you are writing JavaScript without types, the type inference half of the library does nothing for you, and the remaining value is the validation itself, which other libraries also provide.

The interesting constraint is the size target. The README states a bundle size starting at less than 700 bytes, and the example imports the whole namespace with a comment reading 1.31 kB. That number is the reason the API is shaped the way it is, and it is the reason a team would tolerate the composition style described below.

Small functions composed with pipe, not methods on a schema

The design decision that separates Valibot from most schema libraries is stated directly in the README: instead of a few large functions with many methods, the API is many small independent functions, each with a single task. The example shows what that means in practice. A string field is not written as v.string().email().min(8). It is written as v.pipe(v.string(), v.email()) and v.pipe(v.string(), v.minLength(8)). The base schema is one function call, and every additional check is another function call passed as an argument.

That structure has a mechanical consequence. Because each check is a separate exported function, a bundler can follow the import graph and drop the ones you never reference. A method-based API carries the whole class or object with it. The README puts the resulting difference at up to 95 percent reduction compared to Zod, a figure worth treating as a claim about the project's own measurements rather than a guarantee for your application.

The same modularity shows up in the repository layout. There is a library directory, a packages directory, a codemod directory, and a website directory, with pnpm-workspace.yaml at the top level and pnpm as the declared package manager at version 11.5.0. The codemod directory suggests the project ships automated rewrites, and the migration article and migration guide linked from the README are the documented path from Zod.

Data flow through a schema is straightforward. You build a schema value, pass it and an unknown input to parse, and either get the typed output or an exception. The README also documents safeParse for a non-exception-based API and is as a type guard function, so the same schema can serve three call sites with different error handling.

Installing Valibot and parsing your first object

The README does not include an install command, but it links to the npm package page at npmjs.org/package/valibot and to a JSR package at jsr.io/@valibot/valibot, so the package name is valibot. From npm, the install is the usual form.

npm install valibot

After that, the README gives a login schema as the first real example. It imports the namespace, builds an object schema with an email check and a minimum password length, and infers the output type from the schema itself.

import * as v from 'valibot';

const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

type LoginData = v.InferOutput<typeof LoginSchema>;

Calling parse with an empty email and password throws, according to the README, for both fields. Calling it with a valid email and an eight-character password returns the data typed as { email: string; password: string }. If you would rather not handle exceptions, the README points to safeParse and to is, described as a type guard function, with more detail in the parse-data guide on valibot.dev.

One caveat about the import line. The README annotates it with 1.31 kB, which is the size of the full namespace import, not the minimum. The sub-700-byte figure applies when a bundler can remove what you do not use, so the import style in your own code affects the number you end up shipping.

Where Valibot is the wrong choice

The modular API has a cost that the README does not discuss. Every check is a function call wrapped in pipe, so a schema with ten constraints is a nested expression rather than a chain of methods. Teams coming from Zod will find the reading order different, which is exactly why the project maintains a migration guide and a codemod directory. If your codebase has hundreds of schemas and no bundle-size pressure, that rewrite is work with no payoff.

The bundle-size argument also assumes a bundler that performs dead code elimination on your import style. In a Node.js service, a CLI, or a test runner, there is no bundler and no tree shaking, so the modular design buys you nothing at runtime. The library still works, but the headline advantage does not apply. That is a case where choosing Valibot over a larger alternative is a decision made on a benefit you will never collect.

Third, the README presents no compatibility layer for other libraries' schema formats. If your stack expects schemas in a particular shape, for example a form library that consumes a specific object, you should check what adapters exist before assuming they do. The topics list mentions standard-schema, and the release list includes a to-json-schema package release dated 2026-09-11, so there is some interop surface, but the README itself does not document a broad adapter ecosystem.

Finally, error messages are not covered in the README beyond the statement that parse throws. If your product surfaces validation messages to end users, verify the error shape before you build a UI on top of it.

Valibot against Zod, and where the difference actually lands

Zod is the comparison the project itself invites. The README links a migration article titled why migrate to Valibot, a migration guide, and credits Colin McDonnell, the author of Zod, as an influence on the API design. So this is not a rivalry invented by observers.

The difference in approach is structural rather than cosmetic. Zod exposes methods on schema instances, which makes a schema a single object carrying all its behaviour. Valibot exposes free functions that you compose, which makes a schema a pipeline of independently importable pieces. The first style reads more linearly; the second gives a bundler more to remove. The README attributes up to 95 percent bundle reduction to that second property. Whether the number holds for your application depends on how much of the library you use and whether your build step tree shakes at all.

A second practical difference is the extension story. The README argues that independent functions are easier to extend with external code and easier to unit test individually. That is a claim about maintainability rather than a feature you can measure on day one.

Other libraries in the same space appear in what people search for alongside Valibot: TypeBox, ArkType, Yup. This project does not describe how Valibot differs from those, so treat any comparison outside Zod as something to research separately rather than something Valibot documents.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-21. Recent releases include v1.5.0 on 2026-09-09, an i18n release v1.3.0-i18n on 2026-09-14, and a to-json-schema release v1.8.0-to-json-schema on 2026-09-11. Those tagged releases suggest the project publishes feature-scoped versions alongside the main line, which is a pattern that can complicate upgrade planning if you depend on one of the sub-packages rather than the core library.

The root package.json is marked private and carries version 0.0.0, so it is a workspace root rather than a publishable artifact. It declares pnpm at 11.5.0 and TypeScript at ^5.9.3 as development dependencies, and its scripts fan out across the workspace: test, lint, format, build, and a scan script running cve-lite. The build script excludes the website package. That layout tells you the published package comes from one of the subdirectories under packages, not from the root.

Licensing is MIT, stated in the README and in the root package.json. MIT is permissive and imposes no copyleft obligation on your application, but it also provides no warranty, and the licence text itself is the authority rather than any summary. If your organisation has a policy about dependency licences, the LICENSE.md file at the repository root is what your review process should read. Nothing here constitutes legal advice.

Upgrade cost is hard to estimate from the release list alone. Version numbers there already cross 1.5.0 and 1.8.0 for sub-packages, and the presence of a codemod directory implies the project has, at least at some point, needed automated rewrites for users. Check the release notes for the specific version you are moving to before assuming a patch-level bump is free.

Editorial conclusion

Adopt Valibot when bundle size and tree shaking matter, when you validate API payloads, forms or config files, and when you are willing to compose pipelines of small functions rather than call methods on a schema object. Do not adopt it if you need a wide third-party ecosystem of adapters, or if your schemas are already written against Zod and you have no reason to migrate. Before committing, verify two things on your own code: that your bundler actually drops the unused exports (the README claims up to 95 percent reduction compared to Zod, which is a claim to reproduce, not to assume), and that the error shape from safeParse matches what your form or API layer already consumes.

Frequently asked questions

Official sources

1. License: MIT
2. open-circle/valibot on GitHub
3. Project website
4. README
5. Releases