Back to Details

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

目录结构

DirectoryPurposeExamples
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 stateConfig, 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

  1. Create directory: 
    library/src/schemas/yourSchema/
  2. Create files: 
    yourSchema.ts
    , 
    yourSchema.test.ts
    , 
    yourSchema.test-d.ts
    , 
    index.ts
  3. Follow existing patterns (copy similar implementation)
  4. Export from category 
    index.ts
  5. Run 
    pnpm -C library test
  1. 创建目录：
    library/src/schemas/yourSchema/
  2. 创建文件：
    yourSchema.ts
    , 
    yourSchema.test.ts
    , 
    yourSchema.test-d.ts
    , 
    index.ts
  3. 遵循现有代码模式（复制类似实现）
  4. 在分类的
    index.ts
    中导出
  5. 运行
    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]/
TestsSame directory as source, 
.test.ts
suffix
Type testsSame 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

核心原则

  1. Modularity - Small, focused functions; one per file
  2. Zero dependencies - Core library has no runtime deps
  3. 100% test coverage - Required for library
  4. Tree-shakable - Use 
    // @__NO_SIDE_EFFECTS__
    annotation
  5. Type-safe - Full TypeScript with strict mode
  6. ESM only - Imports include 
    .ts
    extensions
  1. 模块化 - 小巧、专注的函数；每个函数对应一个文件
  2. 零依赖 - 核心库无运行时依赖
  3. 100%测试覆盖率 - 核心库必须满足
  4. 可摇树优化 - 使用
    // @__NO_SIDE_EFFECTS__
    注解
  5. 类型安全 - 完整的TypeScript严格模式支持
  6. 仅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/
    ）