Valibot v1 RC is now available

After taking three steps back about a year ago to rewrite the entire library from scratch, Valibot has come back stronger than ever. In the past 12 months, the project has grown from 300k monthly downloads on npm to now more than 4.5 million. Many of you have been waiting for our first stable release, and with this blog post I am happy to announce that we are very very close.

With this announcement post we want to look back on our work of the last months and show you the new features and functions you will enjoy when you upgrade to Valibot v1 RC.

Better API design

In June 2024 we released v0.31.0, introducing our new pipe API and massively improving Valibot's type safety. I recommend reading the blog post we published at the time to learn more. Even though it was a big change, we got a lot of positive feedback. That's why we kept the new mental model and have continued to improve the new API since then.

Better compatibility

A few months later, in September 2024, we intensified our work on Standard Schema. What had been just an idea was now starting to take shape. Together with @colinhacks, the creator of Zod, we developed a first draft of the specification and investigated how it could be integrated into our libraries. Later, @ssalbdivad, the creator of ArkType, joined us to help us get the details right.

Standard Schema could be a game-changer not only for the further adoption and growth of Valibot, but also for the JavaScript ecosystem in general. If you haven't heard of it yet, you should definitely check it out. Thanks to Colin and David for this great collaboration!

Another part of our ecosystem compatibility efforts has been to develop and provide an official JSON Schema solution. Together with @gcornut, we created a new package called @valibot/to-json-schema that can convert Valibot schemas to their JSON Schema representation. I am proud of our implementation because it is fast, highly efficient (1.67 kB gzip), and can handle complex cases such as recursion. If you are interested in this topic, please have a look at our JSON Schema guide.

import { toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const ValibotEmailSchema = v.pipe(v.string(), v.email());
const JsonEmailSchema = toJsonSchema(ValibotEmailSchema);
// -> { type: 'string', format: 'email' }

Better object schema

Our initial object schema implementation was good, but not perfect. It could not distinguish between missing and present but undefined properties, resulting in mismatches between validation logic and generated TypeScript types in edge cases.

Over the past few weeks, we have fixed these issues and are now able to fully support TypeScript's exactOptionalPropertyTypes configuration. We also fixed the order of optional properties in the generated TypeScript types. Thanks to @andersk for driving this effort!

Better tree shaking

@antfu himself created a PR in December 2024 to further improve Valibot's tree shaking capabilities. If you use some of your schemas only for their TypeScript type but not at runtime, for example to validate unknown data, they can now be fully tree-shaken and excluded from your production build, reducing the bundle size of your application even further.

Better documentation

A few weeks ago we made some nice UI and UX improvements to Valibot's documentation and playground. For example, there is now a "play" button to open the code snippets of our guides directly in our playground. Also, you can now enable chapter navigation in Valibot's documentation to make it easier to navigate through the content of a large page.

I would also like to point out that @EltonLobo07 finalized the last pages of our API reference. With more than 600 pages, this was a huge effort driven by several community members over the last year. Thanks to everyone who contributed!

Other highlights

In addition to these bigger changes, we shipped many new functions and improved the implementation of existing ones. For example, we added a function and promise schema along with args, returns, and awaitAsync actions to support validation of JavaScript functions and promises.

We also shipped a rawCheck and rawTransform action to give you full control in edge cases. They allow you to hook into the raw implementation of pipe to write advanced validation and transformation logic.

Another cool addition to Valibot's capabilities is our new metadata feature. This is especially useful for documentation purposes and for deep integration of the schema library with other libraries. For example, an ORM could now provide its own metadata actions such as table, primaryKey and index built on top of Valibot instead of writing everything from scratch.

import * as o from 'orm-actions';
import * as v from 'valibot';

const UserTableSchema = v.pipe(
  v.object({
    id: v.pipe(v.number(), v.integer(), o.primaryKey()),
    name: v.pipe(v.string(), v.nonEmpty(), o.index()),
    email: v.pipe(v.string(), v.email(), o.index()),
    // ...
  }),
  o.table('users')
);

There are many more new exciting functions like assert, rfcEmail and maxWords. Please have a look at the release on GitHub and our API reference for more details.

What's next?

Many more validation actions like ltValue, gtValue, values, notValues, slug, toSnakeCase and btcAddress are already implemented and will be reviewed and merged soon. This shows the great advantage of a modular architecture, as we can add more and more features without increasing the size of your individual bundle. One day, everything you need will be just a Valibot action away. 😎

We expect Valibot to reach v1 in 3 to 6 weeks. Please upgrade now to give us lots of feedback in the meantime. An official migration guide will be available soon, but most of you who are already on >=v0.31.0 will most likely be able to upgrade without touching any existing code.