// Update existing API documentation pages after source code changes. Use when syncing docs with library changes like new parameters, type constraint changes, interface updates, or function renames. Covers common change patterns and verification steps.
| name | repo-website-api-update |
| description | Update existing API documentation pages after source code changes. Use when syncing docs with library changes like new parameters, type constraint changes, interface updates, or function renames. Covers common change patterns and verification steps. |
Guide for syncing API docs with source code changes.
Prerequisite: Read the repo-website-api-create skill for properties.ts and index.mdx patterns.
Update documentation when source code changes:
Do NOT update for: Internal implementation changes (~run method), test changes, non-JSDoc comments.
properties.ts - Match types exactly to source; for optional object keys, keep the plain key name and use a union with undefined as the last option instead of appending ?index.mdx - Signature, generics, parameters, examplesmenu.md if renamed// Before: one overload
export function action<TInput>(requirement: TRequirement): Action<...>;
// After: two overloads (message is optional)
export function action<TInput>(requirement: TRequirement): Action<..., undefined>;
export function action<TInput, TMessage>(requirement: TRequirement, message: TMessage): Action<..., TMessage>;
Update:
TMessage generic to properties.tsmessage parameter to properties.tsindex.mdxproperties.tsindex.mdx// Before
TRequirement extends number
// After
TRequirement extends number | string
Update:
properties.ts(types)/TypeName/properties.ts; if the source key is optional, do not append ? to the key name and model it as a union with undefined lastmenu.md (maintain alphabetical order)Add notice at top of index.mdx (import Link from ~/components):
> **⚠️ Deprecated**: Use <Link href="../newFunction/">\`newFunction\`</Link> instead. Will be removed in v2.0.
When source introduces a type alias:
// Before: TInput extends string | unknown[]
// After: TInput extends LengthInput
properties.ts to reference new type with href(types)/When sync and async variants are added:
When a function changes, check:
(types)/TypeName/)After updating, verify:
href links are validmenu.md updated if renamedproperties.ts → index.mdx → related files| Change | Files to Update |
|---|---|
| New parameter | properties.ts, index.mdx (signature, generics, params, examples) |
| Removed parameter | properties.ts, index.mdx |
| Type change | properties.ts, index.mdx (explanation, examples) |
| Interface change | (types)/TypeName/properties.ts, (types)/TypeName/index.mdx |
| Renamed function | Folder name, all files, menu.md, cross-references |
| Deprecation | index.mdx (add warning) |
Create new API reference pages for the Valibot website at website/src/routes/api/. Use when adding documentation for new schemas, actions, methods, or types. Covers reading source code, creating properties.ts and index.mdx files, updating menu.md, and cross-referencing related APIs.
Write JSDoc comments and inline documentation for Valibot library source code in /library/src/. Use when documenting schemas, actions, methods, or utilities. Covers interface documentation, function overloads, purity annotations, inline comment patterns, and terminology consistency.
Review pull requests and source code changes in /library/src/. Use when reviewing PRs, validating implementation patterns, or checking code quality before merging. Covers code quality checks, type safety, documentation review, test coverage, and common issues to watch for.
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.
Create conceptual documentation and tutorial pages for the Valibot website at website/src/routes/guides/. Use when adding guides about schemas, pipelines, async validation, migration, or other topics. Covers directory structure, MDX templates, frontmatter, and content guidelines.