repo-structure-navigate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Valibot Repository Structure

Valibot 仓库结构

Monorepo Layout

单仓库（Monorepo）布局

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

valibot/
├── library/          # 核心Valibot包（零依赖）
├── packages/
│   ├── i18n/         # 多语言错误提示（支持25+种语言）
│   └── to-json-schema/  # JSON Schema转换器
├── codemod/
│   ├── migrate-to-v0.31.0/  # 版本迁移工具
│   └── zod-to-valibot/      # Zod转Valibot工具
├── website/          # valibot.dev官网（基于Qwik + Vite）
├── brand/            # 品牌资源
├── skills/           # Agent技能（当前目录）
└── prompts/          # 旧版AI Agent指南

Core Library (

/library/src/

)

核心库（

/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

目录	用途	示例
`schemas/`	数据类型验证器	`string/` , `object/` , `array/` , `union/`
`actions/`	验证与转换操作	`email/` , `minLength/` , `trim/` , `transform/`
`methods/`	高级API	`parse/` , `safeParse/` , `pipe/` , `partial/`
`types/`	TypeScript类型定义	`schema.ts` , `issue.ts` , `dataset.ts`
`utils/`	内部辅助工具（前缀 `_` ）	`_addIssue/` , `_stringify/` , `ValiError/`
`storages/`	全局状态管理	配置、消息存储

Schema Categories

Schema分类

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

基础类型：

string

number

boolean

bigint

date

symbol

blob

file

对象类型：

object

strictObject

looseObject

objectWithRest

数组类型：

array

tuple

strictTuple

looseTuple

tupleWithRest

高级类型：

union

variant

intersect

record

map

set

lazy

custom

修饰符：

optional

nullable

nullish

nonNullable

nonNullish

nonOptional

Action Types

Action类型

Validation (return issues):

email

url

uuid

regex

minLength

maxValue

check

Transformation (modify data):

trim

toLowerCase

toUpperCase

mapItems

transform

Metadata:

brand

flavor

metadata

description

title

验证类（返回错误信息）：

email

url

uuid

regex

minLength

maxValue

check

转换类（修改数据）：

trim

toLowerCase

toUpperCase

mapItems

transform

元数据类：

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

每个schema/action/method都有独立目录：

schemas/string/
├── string.ts        # 实现代码
├── string.test.ts   # 运行时测试
├── string.test-d.ts # 类型测试
└── index.ts         # 导出入口

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>;

Schemas定义数据类型：

typescript

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

Actions在流水线中执行验证/转换：

typescript

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

Methods提供API函数：

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

BaseSchema

BaseValidation

BaseTransformation

- 基础接口

InferOutput<T>

InferInput<T>

InferIssue<T>

- 类型推断

```
Config
```
,
```
ErrorMessage<T>
```
,
```
BaseIssue<T>
```
- 配置与错误相关
```
'~standard'
```
属性 - 兼容Standard Schema

Website (

/website/src/routes/

)

官网（

/website/src/routes/

）

API Documentation

API文档

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

routes/api/
├── (schemas)/string/     # Schema文档
│   ├── index.mdx         # MDX内容
│   └── properties.ts     # 类型定义
├── (actions)/email/      # Action文档
├── (methods)/parse/      # Method文档
├── (types)/StringSchema/ # 类型文档
└── menu.md               # 导航菜单

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

routes/guides/
├── (get-started)/       # 入门、安装
├── (main-concepts)/     # Schema、流水线、解析
├── (schemas)/           # 对象、数组、联合类型
├── (advanced)/          # 异步、i18n、JSON Schema
├── (migration)/         # 版本升级
└── menu.md              # 导航菜单

Development

开发相关

Playground

实验场

Use

library/playground.ts

for quick experimentation.

使用

library/playground.ts

进行快速实验。

Adding a Schema/Action

添加新的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
```

创建目录：
```
library/src/schemas/yourSchema/
```

创建文件：

yourSchema.ts

yourSchema.test.ts

yourSchema.test-d.ts

index.ts

遵循现有代码模式（复制类似实现）
在分类的
```
index.ts
```
中导出
运行
```
pnpm -C library test
```

Modifying Core Types

修改核心类型

⚠️ Changes to

library/src/types/

affect the entire library. Always run full test suite.

⚠️ 修改

library/src/types/

会影响整个库。请务必运行完整测试套件。

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

查找内容	位置
Schema实现代码	`library/src/schemas/[name]/[name].ts`
Action实现代码	`library/src/actions/[name]/[name].ts`
Method实现代码	`library/src/methods/[name]/[name].ts`
类型定义	`library/src/types/`
内部辅助工具	`library/src/utils/`
多语言错误提示	`packages/i18n/[lang]/`
API文档页面	`website/src/routes/api/(category)/[name]/`
指南文档页面	`website/src/routes/guides/(category)/[name]/`
运行时测试	与源码同目录，后缀 `.test.ts`
类型测试	与源码同目录，后缀 `.test-d.ts`

Commands

命令

bash

undefined

bash

undefined

Library

核心库

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

pnpm -C library build # 构建 pnpm -C library test # 运行测试 pnpm -C library lint # 代码检查 pnpm -C library format # 代码格式化

Website

官网

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

pnpm -C website dev # 启动开发服务器 pnpm -C website build # 生产构建

Root

根目录

pnpm install # Install all pnpm format # Format all

undefined

pnpm install # 安装所有依赖 pnpm format # 格式化所有代码

undefined

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

模块化 - 小巧、专注的函数；每个函数对应一个文件
零依赖 - 核心库无运行时依赖
100%测试覆盖率 - 核心库必须满足
可摇树优化 - 使用
```
// @__NO_SIDE_EFFECTS__
```
注解
类型安全 - 完整的TypeScript严格模式支持
仅ESM - 导入需包含
```
.ts
```
扩展名

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

建议：

遵循现有代码模式
编写运行时和类型测试
添加JSDoc文档
保持函数小巧且专注
检查对包体积的影响

禁止：

添加外部依赖
修改核心类型后不运行完整测试
跳过测试
创建大型多用途函数
修改生成文件（
```
dist/
```
,
```
coverage/
```
）

repo-structure-navigate

Original

Translation

Valibot Repository Structure

Valibot 仓库结构

Monorepo Layout

单仓库（Monorepo）布局

Core Library (/library/src/)

核心库（/library/src/）

Directory Structure

目录结构

Schema Categories

Schema分类

Action Types

Action类型

File Naming Convention

文件命名规范

Core Patterns

核心模式

Key Types

关键类型

Website (/website/src/routes/)

官网（/website/src/routes/）

API Documentation

API文档

Guides

指南文档

Development

开发相关

Playground

实验场

Adding a Schema/Action

添加新的Schema/Action

Modifying Core Types

修改核心类型

Quick Lookups

快速查询

Commands

命令

Library

核心库

Website

官网

Root

根目录

Key Principles

核心原则

Do's and Don'ts

注意事项

Core Library (
`/library/src/`
)

核心库（
`/library/src/`
）

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

官网（
`/website/src/routes/`
）