Valibot Repository Structure

Monorepo Layout

valibot/ ├── library/ # Core valibot package (zero dependencies) ├── packages/ │ ├── i18n/ # Translated error messages (25+ languages) │ └── to-json-schema/ # JSON Schema converter ├── codemod/ │ ├── migrate-to-v0.31.0/ # Version migration │ └── zod-to-valibot/ # Zod converter ├── website/ # valibot.dev (Qwik + Vite) ├── brand/ # Brand assets ├── skills/ # Agent skills (this folder) └── prompts/ # Legacy AI agent guides

Core Library (/library/src/ )

Directory Structure

Directory Purpose Examples

schemas/

Data type validators string/ , object/ , array/ , union/

actions/

Validation & transformation email/ , minLength/ , trim/ , transform/

methods/

High-level API parse/ , safeParse/ , pipe/ , partial/

types/

TypeScript definitions schema.ts , issue.ts , dataset.ts

utils/

Internal helpers (prefixed _ ) _addIssue/ , _stringify/ , ValiError/

storages/

Global state Config, message storage

Schema Categories

• Primitives: string , number , boolean , bigint , date , symbol , blob , file

• Objects: object , strictObject , looseObject , objectWithRest

• Arrays: array , tuple , strictTuple , looseTuple , tupleWithRest

• Advanced: union , variant , intersect , record , map , set , lazy , custom

• Modifiers: optional , nullable , nullish , nonNullable , nonNullish , nonOptional

Action Types

Validation (return issues): email , url , uuid , regex , minLength , maxValue , check

Transformation (modify data): trim , toLowerCase , toUpperCase , mapItems , transform

Metadata: brand , flavor , metadata , description , title

File Naming Convention

Each schema/action/method has its own directory:

schemas/string/ ├── string.ts # Implementation ├── string.test.ts # Runtime tests ├── string.test-d.ts # Type tests └── index.ts # Re-export

Core Patterns

Schemas define data types:

export interface StringSchema<TMessage> extends BaseSchema<...> { readonly kind: 'schema'; readonly type: 'string'; // ... }

Actions validate/transform in pipelines:

export interface EmailAction<TInput, TMessage> extends BaseValidation<...> { readonly kind: 'validation'; readonly type: 'email'; // ... }

Methods provide API functions:

export function parse<TSchema>( schema: TSchema, input: unknown ): InferOutput<TSchema>;

Key Types

• BaseSchema , BaseValidation , BaseTransformation

• Base interfaces

• InferOutput<T> , InferInput<T> , InferIssue<T>

• Type inference

• Config , ErrorMessage<T> , BaseIssue<T>

• Configuration and errors

• '~standard' property - Standard Schema compatibility

Website (/website/src/routes/ )

API Documentation

routes/api/ ├── (schemas)/string/ # Schema docs │ ├── index.mdx # MDX content │ └── properties.ts # Type definitions ├── (actions)/email/ # Action docs ├── (methods)/parse/ # Method docs ├── (types)/StringSchema/ # Type docs └── menu.md # Navigation

Guides

routes/guides/ ├── (get-started)/ # Intro, installation ├── (main-concepts)/ # Schemas, pipelines, parsing ├── (schemas)/ # Objects, arrays, unions ├── (advanced)/ # Async, i18n, JSON Schema ├── (migration)/ # Version upgrades └── menu.md # Navigation

Development

Playground

Use library/playground.ts for quick experimentation.

Adding a Schema/Action

• Create directory: library/src/schemas/yourSchema/

• Create files: yourSchema.ts , yourSchema.test.ts , yourSchema.test-d.ts , index.ts

• Follow existing patterns (copy similar implementation)

• Export from category index.ts

• Run pnpm -C library test

Modifying Core Types

⚠️ Changes to library/src/types/ affect the entire library. Always run full test suite.

Quick Lookups

Looking for... Location

Schema implementation library/src/schemas/[name]/[name].ts

Action implementation library/src/actions/[name]/[name].ts

Method implementation library/src/methods/[name]/[name].ts

Type definitions library/src/types/

Internal utilities library/src/utils/

Error messages (i18n) packages/i18n/[lang]/

API docs page website/src/routes/api/(category)/[name]/

Guide page website/src/routes/guides/(category)/[name]/

Tests Same directory as source, .test.ts suffix

Type tests Same directory as source, .test-d.ts suffix

Commands

Library

pnpm -C library build # Build pnpm -C library test # Run tests pnpm -C library lint # Lint pnpm -C library format # Format

Website

pnpm -C website dev # Dev server pnpm -C website build # Production build

Root

pnpm install # Install all pnpm format # Format all

Key Principles

• Modularity - Small, focused functions; one per file

• Zero dependencies - Core library has no runtime deps

• 100% test coverage - Required for library

• Tree-shakable - Use // @NO_SIDE_EFFECTS annotation

• Type-safe - Full TypeScript with strict mode

• ESM only - Imports include .ts extensions

Do's and Don'ts

Do:

• Follow existing code patterns

• Write runtime and type tests

• Add JSDoc documentation

• Keep functions small and focused

• Check bundle size impact

Don't:

• Add external dependencies

• Modify core types without full test run

• Skip tests

• Create large multi-purpose functions

• Modify generated files (dist/ , coverage/ )