repo-structure-navigate

Original：🇺🇸 English

Translated

Navigate the Valibot repository structure. Use when looking for files, understanding the codebase layout, finding schema/action/method implementations, locating tests, API docs, or guide pages. Covers monorepo layout, library architecture, file naming conventions, and quick lookups.

1installs

Sourceopen-circle/valibot

Added on2026-02-20

NPX Install

npx skill4agent add open-circle/valibot repo-structure-navigate

SKILL.md Content

View Translation Comparison →

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:

typescript

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

Actions validate/transform in pipelines:

typescript

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

Methods provide API functions:

typescript

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

bash

# 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/
```
)

repo-structure-navigate

NPX Install

Tags

SKILL.md Content

Valibot Repository Structure

Monorepo Layout

Core Library (
`/library/src/`
)

Directory Structure

Schema Categories

Action Types

File Naming Convention

Core Patterns

Key Types

Website (
`/website/src/routes/`
)

API Documentation

Guides

Development

Playground

Adding a Schema/Action

Modifying Core Types

Quick Lookups

Commands

Key Principles

Do's and Don'ts

repo-structure-navigate

NPX Install

Tags

SKILL.md Content

Valibot Repository Structure

Monorepo Layout

Core Library (/library/src/)

Directory Structure

Schema Categories

Action Types

File Naming Convention

Core Patterns

Key Types

Website (/website/src/routes/)

API Documentation

Guides

Development

Playground

Adding a Schema/Action

Modifying Core Types

Quick Lookups

Commands

Key Principles

Do's and Don'ts

Core Library (
`/library/src/`
)

Website (
`/website/src/routes/`
)