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.
Guide for creating new API reference pages at website/src/routes/api/.
/library/src//website/src/routes/api/(category)/[name]/properties.ts with type definitionsindex.mdx with documentationmenu.mdwebsite/src/routes/api/
├── (schemas)/string/
│ ├── index.mdx # Documentation content
│ └── properties.ts # Type definitions for Property component
├── (actions)/email/
├── (methods)/parse/
├── (types)/StringSchema/
└── menu.md # Navigation (alphabetical order)
Categories: (schemas), (actions), (methods), (types), (utils), (async), (storages)
From /library/src/schemas/string/string.ts:
// 1. Issue interface → Document in (types)/StringIssue/
export interface StringIssue extends BaseIssue<unknown> { ... }
// 2. Schema interface → Document in (types)/StringSchema/
export interface StringSchema<TMessage extends ErrorMessage<StringIssue> | undefined>
extends BaseSchema<string, string, StringIssue> { ... }
// 3. Function overloads → Main documentation
export function string(): StringSchema<undefined>;
export function string<const TMessage>(message: TMessage): StringSchema<TMessage>;
// 4. JSDoc → Description, hints, parameter docs
/**
* Creates a string schema.
*
* Hint: This is an example hint.
*
* @param message The error message.
*
* @returns A string schema.
*/
JSDoc hints become blockquotes in the Explanation section:
> This is an example hint.
TMessage extends ErrorMessage<...> | undefined)Import and define properties matching source code:
import type { PropertyProps } from '~/components';
export const properties: Record<string, PropertyProps> = {
// Generics (use modifier: 'extends')
TMessage: {
modifier: 'extends',
type: {
type: 'union',
options: [
{
type: 'custom',
name: 'ErrorMessage',
href: '../ErrorMessage/',
generics: [
{ type: 'custom', name: 'StringIssue', href: '../StringIssue/' },
],
},
'undefined',
],
},
},
// Parameters (reference generic or direct type)
message: {
type: { type: 'custom', name: 'TMessage' },
},
// Return type
Schema: {
type: {
type: 'custom',
name: 'StringSchema',
href: '../StringSchema/',
generics: [{ type: 'custom', name: 'TMessage' }],
},
},
};
For optional object keys from TypeScript source such as key?: string, do not append ? to the property name in properties.ts.
Use the plain key name and represent optionality in the value type with undefined as the last union option: