write-api-reference

Writing API Reference Pages

Goal

Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.

Each page documents one API. If the API has sub-methods (like cookies.set()), document them on the same page. If two APIs are independent, they get separate pages.

Structure

Identify which category the API belongs to, then follow the corresponding template.

Categories

1. Function (cookies, fetch, generateStaticParams): signature, params/returns, methods table, examples
2. Component (Link, Image, Script): props summary table, individual prop docs, examples
3. File convention (page, layout, route): definition, code showing the convention, props, behavior, examples
4. Directive (use client, use cache): definition, usage, serialization/boundary rules, reference
5. Config option (basePath, images, etc.): definition, config code, behavioral sections

Template

---
title: {API name}
description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
---

{One sentence defining what it does and where it's used.}

```tsx filename="path/to/file.tsx" switcher
// Minimal working usage
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Reference

{For functions: methods/params table, return type.}
{For components: props summary table, then `#### propName` subsections.}
{For file conventions: `### Props` with `#### propName` subsections.}
{For directives: usage rules and serialization constraints.}
{For config: options table or individual option docs.}

### {Subsection name}

{Description + code example + table of values where applicable.}

## Good to know

- {Default behavior or implicit effects.}
- {Caveats, limitations, or version-specific notes.}
- {Edge cases the developer should be aware of.}

## Examples

### {Example name}

{Brief context, 1-2 sentences.}

```tsx filename="path/to/file.tsx" switcher
// Complete working example
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Version History

| Version  | Changes         |
| -------- | --------------- |
| `vX.Y.Z` | {What changed.} |

Category-specific notes:

• Functions: Lead with the function signature and await if async. Document methods in a table if the return value has methods (like cookies). Document options in a separate table if applicable.
• Components: Start with a props summary table (| Prop | Example | Type | Required |). Then document each prop under #### propName with description, code example, and value table where useful.
• File conventions: Show the default export signature with TypeScript types. Document each prop (params, searchParams, etc.) under #### propName with a route/URL/value example table.
• Directives: No ## Reference section. Use ## Usage instead, showing correct placement. Document serialization constraints and boundary rules.
• Config options: Show the next.config.ts snippet. Use subsections for each behavioral aspect.

Rules

1. Lead with what it does. First sentence defines the API. No preamble.
2. Show working code immediately. A minimal usage example appears right after the opening sentence, before ## Reference.
3. Use switcher for tsx/jsx pairs. Always include both. Always include filename="path/to/file.ext".
4. Use highlight={n} for key lines. Highlight the line that demonstrates the API being documented.
5. Tables for simple APIs, subsections for complex ones. If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a #### subsection.
6. Behavior section uses > **Good to know**:or## Good to know. Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
7. Examples section uses ### Example Name subsections. Each example solves one specific use case.
8. Version History table at the end. Include when the API has changed across versions. Omit for new APIs.
9. No em dashes. Use periods, commas, or parentheses instead.
10. Mechanical, observable language. Describe what happens, not how it feels. "Returns an object" not "gives you an object".
11. Link to related docs with relative paths. Use /docs/app/... format.
12. No selling or justifying. No "powerful", "easily", "simply". State what the API does.

13. Bridge new framework terms with legacy or generic vocabulary. When the API renames or differentiates from a prior concept (Pages-era term, generic web term, REST vocabulary), include one such synonym in the frontmatter description and once in prose. Example: description: "Use Dynamic Segments to read URL parameters and generate routes from dynamic data." mentions "URL parameters" alongside "Dynamic Segments". One synonym, folded into natural prose. No separate "Synonyms" or "Also known as" section, no keyword stuffing. Goal: preserve discoverability for users still searching the old vocabulary even when the framework has moved on.

Workflow

1. Ask for reference material. Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
2. Identify the API category (function, component, file convention, directive, config).
3. Research the implementation. Read the source code to understand params, return types, edge cases, and defaults.
4. Check e2e tests. Search test/ for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
5. Check existing related docs for linking opportunities and to avoid duplication.
6. Write using the appropriate category template. Follow the rules above.
7. Review against the rules. Verify: one sentence opener, immediate code example, correct switcher/filename usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.

References

Read these pages in docs/01-app/03-api-reference/ before writing. They demonstrate the patterns above.

• 04-functions/cookies.mdx - Function with methods table, options table, and behavior notes
• 03-file-conventions/page.mdx - File convention with props subsections and route/URL/value tables
• 02-components/link.mdx - Component with props summary table and detailed per-prop docs
• 01-directives/use-client.mdx - Directive with usage section and serialization rules
• 04-functions/fetch.mdx - Function with troubleshooting section and version history