Começando com Valibot

O TypeScript oferece segurança de tipos em tempo de compilação, mas não pode protegê-lo em tempo de execução. Quando dados chegam de um envio de formulário, uma resposta de API ou um arquivo de configuração, os tipos do TypeScript já se foram. Essa é a lacuna que as bibliotecas de validação de schema preenchem — e é exatamente onde o Valibot se destaca.

Este guia apresenta o que é o Valibot, como funciona e como começar a usá-lo para validação de schema TypeScript em projetos frontend reais.

O Que É Valibot e Por Que Usá-lo?

Valibot é uma biblioteca modular de validação de schema, TypeScript-first. Ela valida dados desconhecidos em tempo de execução e infere tipos TypeScript estáticos a partir de seus schemas, então seu schema se torna a única fonte de verdade tanto para segurança em tempo de execução quanto para tipos em tempo de compilação.

O que a diferencia é sua arquitetura. Em vez de um grande objeto com métodos encadeados (a abordagem que o Zod adota), o Valibot é construído a partir de muitas funções pequenas e independentes. Os bundlers podem fazer tree-shake de tudo que você não usa, o que mantém seu bundle de produção mínimo — frequentemente em torno de ~1 KB dependendo do uso. Essa é uma vantagem significativa em aplicações frontend onde o tamanho do bundle afeta diretamente o tempo de carregamento.

O Valibot é estável, ativamente mantido e está na versão v1+, tornando-o uma escolha sólida para uso em produção.

Definindo Seu Primeiro Schema Valibot

Definir um schema no Valibot se parece com escrever um tipo TypeScript, mas é executado em tempo de execução:

import * as v from 'valibot'

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

Você pode então derivar um tipo TypeScript diretamente do schema:

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

Sem duplicação. Seu schema e seu tipo permanecem sincronizados automaticamente.

Analisando e Validando Dados

O Valibot oferece duas formas principais de validar dados.

parse lança um erro se a validação falhar:

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

safeParse retorna um objeto de resultado em vez de lançar erro, o que é útil quando você quer lidar com erros sem try/catch:

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

if (!result.success) {
  console.log(result.issues) // Detalhes estruturados do erro
}

Para validação de formulários, safeParse geralmente é a melhor escolha — mantém o tratamento de erros limpo e previsível.

Pipelines de Validação Composáveis

A função pipe do Valibot permite encadear etapas de validação e transformação. Um pipeline sempre começa com um schema base, seguido por ações que são executadas em sequência:

const EmailSchema = v.pipe(
  v.string('Email deve ser uma string.'),
  v.nonEmpty('Por favor, insira seu email.'),
  v.email('Formato de email inválido.')
)

Cada ação recebe a saída da anterior. Isso torna direto aplicar regras como comprimento mínimo, formatos específicos ou restrições personalizadas — tudo com mensagens de erro claras e específicas por campo que você controla.

Valibot vs Zod: A Diferença Principal

Ambas as bibliotecas resolvem o mesmo problema central. A diferença prática está na filosofia de design e no impacto no bundle.

Se você já está usando Zod, a migração é direta — os conceitos mapeiam de perto, e a documentação do Valibot inclui orientação para desenvolvedores fazendo a transição.

Ecossistema e Próximos Passos

O Valibot integra-se bem com bibliotecas de formulários populares. A biblioteca Superforms para SvelteKit tem suporte de primeira classe ao Valibot, e existem adaptadores para React Hook Form e outras ferramentas.

Para equipes que precisam de saída JSON Schema — para documentação de API ou especificações OpenAPI — o pacote separado @valibot/to-json-schema cuida disso. Internacionalização para mensagens de erro também é suportada via @valibot/i18n, tornando o Valibot prático para aplicações multilíngues.

Conclusão

O Valibot oferece segurança de tipos em tempo de execução, inferência limpa de TypeScript e uma pegada mínima — sem a sobrecarga de alternativas mais pesadas. Instale-o, defina um schema e deixe sua lógica de validação se tornar a fundação sobre a qual seus tipos são construídos.

npm install valibot

A partir daí, seus schemas podem crescer com sua aplicação — de simples verificações de string a objetos aninhados complexos — sem nunca inflar seu bundle.

Perguntas Frequentes

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.