repo-structure-navigate

---
name: repo-structure-navigate
description: 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.
---

# 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](https://github.com/standard-schema/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

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`

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

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

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

More agent context in fabian-hiller/valibot

7 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• open-circle/valibot9k