Valibot para TypeScript: guia completo com exemplos

Introdução: o que é Valibot e para que serve?

\n\n

Valibot é uma biblioteca moderna, modular e leve para validação de dados em TypeScript e JavaScript. Ao contrário de gigantes como Zod ou Joi, o Valibot foi projetado com foco no tamanho mínimo do bundle e tree-shaking (capacidade de remover código não utilizado).

\n\n

A filosofia principal do Valibot é "pague apenas pelo que você usa". Se você precisa validar apenas uma string quanto ao comprimento mínimo, você importa apenas string e minLength, e não a biblioteca inteira. Isso torna o Valibot a escolha ideal para projetos onde o tamanho do bundle JavaScript final é importante (por exemplo, para aplicativos móveis ou bibliotecas de componentes).

\n\n

A biblioteca é totalmente tipada e oferece excelente integração com TypeScript, inferindo automaticamente os tipos a partir dos esquemas de validação. O Valibot suporta tanto primitivos simples (strings, números, booleanos) quanto estruturas complexas (objetos, arrays, tipos union, esquemas recursivos).

\n\n

Instalação

\n\n

O Valibot é distribuído através do gerenciador de pacotes npm. Para instalar, execute o seguinte comando no terminal do seu projeto:

\n\n

npm install valibot

\n\n

Se você usa yarn:

\n\n

yarn add valibot

\n\n

Para pnpm:

\n\n

pnpm add valibot

\n\n

Após a instalação, você pode importar as funções necessárias no seu arquivo TypeScript:

\n\n

import { string, number, object, minLength, maxValue } from 'valibot';

\n\n

Início rápido com exemplo de código

\n\n

Vamos criar um esquema de validação simples para um formulário de registro de usuário. Validaremos nome, email e idade.

\n\n

import { object, string, number, email, minLength, maxValue, safeParse } from 'valibot';\n\n// 1. Definir o esquema\nconst UserSchema = object({\n  name: string([minLength(2, 'O nome deve ter no mínimo 2 caracteres')]),\n  email: string([email('Email inválido')]),\n  age: number([maxValue(120, 'A idade não pode ser maior que 120')])\n});\n\n// 2. Dados para validar\nconst inputData = {\n  name: 'Ana',\n  email: 'ana@exemplo.com',\n  age: 30\n};\n\n// 3. Validar\nconst result = safeParse(UserSchema, inputData);\n\nif (result.success) {\n  console.log('Dados válidos:', result.output);\n  // result.output tem o tipo { name: string; email: string; age: number; }\n} else {\n  console.error('Erros de validação:', result.issues);\n  // result.issues — array de objetos com descrição dos erros\n}

\n\n

Neste exemplo, usamos safeParse — um método seguro que não lança exceção, mas retorna um objeto com o campo success. Se a validação for bem-sucedida, result.output conterá os dados validados com os tipos corretos.

\n\n

Métodos e funções principais

\n\n

O Valibot fornece várias funções para criar esquemas. Vamos ver as mais importantes.

\n\n

1. string()

\n

O que faz: Cria um esquema para validação de valores string. Aceita um array opcional de validadores para verificações adicionais (comprimento, padrão, etc.).

\n

Parâmetros:

\n

\n
• validations (opcional): array de funções validadoras, como minLength, maxLength, email, url, regex e outras.
\n

\n

Exemplo:

\n

import { string, minLength, maxLength, email } from 'valibot';\n\nconst UsernameSchema = string([minLength(3), maxLength(20)]);\nconst EmailSchema = string([email()]);\n\nconsole.log(safeParse(UsernameSchema, 'Jo')); // { success: false, issues: [...] }\nconsole.log(safeParse(EmailSchema, 'teste@teste.com')); // { success: true, output: 'teste@teste.com' }

\n\n

2. number()

\n

O que faz: Cria um esquema para validação de valores numéricos. Suporta c