Hooks and utilities

A registry holds more than components. A React hook or a plain function is a package like any other — its own folder, version, changelog and page — and its docs are generated from its TypeScript and JSDoc the way a component's props table is.

Scaffolding

1pnpm gen hook      # scope → name (use-…) → visibility
2pnpm gen util      # scope → name → visibility

A hook package has a use-<name>.ts, an example, a spec (with renderHook) and a README; a util package has a <name>.ts, a spec and a README. Both share the component template's tooling (tsconfig, ESLint, tsup, CHANGELOG) and publish the same way. A util package has no React dependency at all.

What the docs show

For every exported function whose name starts with a lowercase letter — hooks are useX, utilities are anything else; PascalCase exports are treated as components — the site shows:

• the signature, as TypeScript prints it (useToggle(initial?: boolean): [boolean, () => void]), one per overload;
• a parameters table: name, type, default (as written in the signature, initial = false), and the @param text — the same columns as a component's props table;
• the return type and the @returns text;
• each @example block as code (a ```ts fence inside the tag is fine).

Hooks additionally get live examples exactly like components: use-<name>.example.tsx exports small components that use the hook, and the Examples tab and the catalog page run them.

Everything above comes from the source file. The same information is written into the package's docs.json on build, so a published version documents itself.

The JSDoc convention

Every exported function carries a JSDoc block with:

1/**
2 * One or two sentences on what it does and when to reach for it.
3 *
4 * @param value   What the parameter means, not just its type.
5 * @returns       What comes back, and under what conditions it differs.
6 * @example
7 * ```ts
8 * formatPrice(1999, "USD"); // → "$19.99"
9 * ```
10 */

• The first paragraph is the description; keep it to the point.
• One @param per parameter, matched by name. A parameter without one shows an empty description — the type alone is rarely enough.
• @returns is worth writing even when the type is obvious: say what the value means.
• At least one @example, runnable as written. For a hook, *.example.tsx is the better place for a worked example because it runs live; keep @example for the one-liner.

The generators write a block in this shape with TODO text; replace the text, keep the tags.

Related

• Components
• Generators
• Publishing