Docs Writer Reference

Reference Page Writer

Quick Reference

Page Type Decision Tree

1. Is it a Hook? Use Type A (Hook/Function) 2. Is it a React component (<Something>)? Use Type B (Component) 3. Is it a compiler configuration option? Use Type C (Configuration) 4. Is it a directive ('use something')? Use Type D (Directive) 5. Is it an ESLint rule? Use Type E (ESLint Rule) 6. Is it listing multiple APIs? Use Type F (Index/Category)

Component Selection

For component selection and patterns, invoke /docs-components.

---

Voice & Style

Voice: Authoritative technical reference writer Tone: Precise, comprehensive, neutral

For tone, capitalization, jargon, and prose patterns, invoke /docs-voice.

Do:

• Start with single-line description: "useState is a React Hook that lets you..."
• Include Parameters, Returns, Caveats sections for every API
• Document edge cases most developers will encounter
• Use section dividers between major sections
• Include "See more examples below" links
• Be assertive, not hedging - "This is designed for..." not "This helps avoid issues with..."
• State facts, not benefits - "The callback always accesses the latest values" not "This helps avoid stale closures"
• Use minimal but meaningful names - onEvent or onTick over onSomething

Don't:

• Skip the InlineToc component
• Omit error cases or caveats
• Use conversational language
• Mix teaching with reference (that's Learn's job)
• Document past bugs or fixed issues
• Include niche edge cases (e.g., this binding, rare class patterns)
• Add phrases explaining "why you'd want this" - the Usage section examples do that
• Exception: Pitfall and DeepDive asides can use slightly conversational phrasing

---

Page Templates

Type A: Hook/Function

When to use: Documenting React hooks and standalone functions (useState, useEffect, memo, lazy, etc.)

---
title: hookName
---

<Intro>

`hookName` is a React Hook that lets you [brief description].

const result = hookName(arg)

</Intro>

<InlineToc />

---

## Reference {/*reference*/}

### `hookName(arg)` {/*hookname*/}

Call `hookName` at the top level of your component to...

[signature example with annotations]

[See more examples below.](#usage)

#### Parameters {/*parameters*/}
* `arg`: Description of the parameter.

#### Returns {/*returns*/}
Description of return value.

#### Caveats {/*caveats*/}
* Important caveat about usage.

---

## Usage {/*usage*/}

### Common Use Case {/*common-use-case*/}
Explanation with Sandpack examples...

---

## Troubleshooting {/*troubleshooting*/}

### Common Problem {/*common-problem*/}
How to solve it...

---

Type B: Component

When to use: Documenting React components (Suspense, Fragment, Activity, StrictMode)

---
title: <ComponentName>
---

<Intro>

`<ComponentName>` lets you [primary action].

<ComponentName prop={value}> <Children /> </ComponentName>

</Intro>

<InlineToc />

---

## Reference {/*reference*/}

### `<ComponentName>` {/*componentname*/}

[Component purpose and behavior]

#### Props {/*props*/}

* `propName`: Description of the prop...
* **optional** `optionalProp`: Description...

#### Caveats {/*caveats*/}

* [Caveats specific to this component]

Key differences from Hook pages:

• Title uses JSX syntax: <ComponentName>
• Uses #### Props instead of #### Parameters
• Reference heading uses JSX: ` ### <ComponentName> `

---

Type C: Configuration

When to use: Documenting React Compiler configuration options

---
title: optionName
---

<Intro>

The `optionName` option [controls/specifies/determines] [what it does].

</Intro>

{ optionName: 'value' // Quick example }

<InlineToc />

---

## Reference {/*reference*/}

### `optionName` {/*optionname*/}

[Description of the option's purpose]

#### Type {/*type*/}

'value1' | 'value2' | 'value3'

#### Default value {/*default-value*/}

`'value1'`

#### Options {/*options*/}

- **`'value1'`** (default): Description
- **`'value2'`**: Description
- **`'value3'`**: Description

#### Caveats {/*caveats*/}

* [Usage caveats]

---

Type D: Directive

When to use: Documenting directives like 'use server', 'use client', 'use memo'

---
title: "'use directive'"
titleForTitleTag: "'use directive' directive"
---

<RSC>

`'use directive'` is for use with [React Server Components](/reference/rsc/server-components).

</RSC>

<Intro>

`'use directive'` marks [what it marks] for [purpose].

function MyComponent() { 'use directive'; // ... }

</Intro>

<InlineToc />

---

## Reference {/*reference*/}

### `'use directive'` {/*use-directive*/}

Add `'use directive'` at the beginning of [location] to [action].

#### Caveats {/*caveats*/}

* `'use directive'` must be at the very beginning...
* The directive must be written with single or double quotes, not backticks.
* [Other placement/syntax caveats]

Key characteristics:

• Title includes quotes: title: "'use server'"
• Uses titleForTitleTag for browser tab title
• <RSC> block appears before <Intro>
• Caveats focus on placement and syntax requirements

---

Type E: ESLint Rule

When to use: Documenting ESLint plugin rules

---
title: rule-name
---

<Intro>
Validates that [what the rule checks].
</Intro>

## Rule Details {/*rule-details*/}

[Explanation of why this rule exists and React's underlying assumptions]

## Common Violations {/*common-violations*/}

[Description of violation patterns]

### Invalid {/*invalid*/}

Examples of incorrect code for this rule:

// X Missing dependency useEffect(() => { console.log(count); }, []); // Missing 'count'

### Valid {/*valid*/}

Examples of correct code for this rule:

// checkmark All dependencies included useEffect(() => { console.log(count); }, [count]);

## Troubleshooting {/*troubleshooting*/}

### [Problem description] {/*problem-slug*/}

[Solution]

## Options {/*options*/}

[Configuration options if applicable]

Key characteristics:

• Intro is a single "Validates that..." sentence
• Uses "Invalid"/"Valid" sections with emoji-prefixed code comments
• Rule Details explains "why" not just "what"

---

Type F: Index/Category

When to use: Overview pages listing multiple APIs in a category

---
title: "Built-in React [Type]"
---

<Intro>

*Concept* let you [purpose]. Brief scope statement.

</Intro>

---

## Category Name {/*category-name*/}

*Concept* explanation with [Learn section link](/learn/topic).

To [action], use one of these [Type]:

* [`apiName`](/reference/react/apiName) lets you [action].
* [`apiName`](/reference/react/apiName) declares [thing].

function Example() { const value = useHookName(args); }

---

## Your own [Type] {/*your-own-type*/}

You can also [define your own](/learn/topic) as JavaScript functions.

Key characteristics:

• Title format: "Built-in React [Type]"
• Italicized concept definitions
• Horizontal rules between sections
• Closes with "Your own [Type]" section

---

Advanced Patterns

Multi-Function Documentation

When to use: When a hook returns a function that needs its own documentation (useState's setter, useReducer's dispatch)

### `hookName(args)` {/*hookname*/}

[Main hook documentation]

#### Parameters {/*parameters*/}
#### Returns {/*returns*/}
#### Caveats {/*caveats*/}

---

### `set` functions, like `setSomething(nextState)` {/*setstate*/}

The `set` function returned by `hookName` lets you [action].

#### Parameters {/*setstate-parameters*/}
#### Returns {/*setstate-returns*/}
#### Caveats {/*setstate-caveats*/}

Key conventions:

• Horizontal rule (---) separates main hook from returned function
• Heading IDs include prefix: {/*setstate-parameters*/} vs {/*parameters*/}
• Use generic names: "set functions" not "setCount"

---

Compound Return Objects

When to use: When a function returns an object with multiple properties/methods (createContext)

### `createContext(defaultValue)` {/*createcontext*/}

[Main function documentation]

#### Returns {/*returns*/}

`createContext` returns a context object.

**The context object itself does not hold any information.** It represents...

* `SomeContext` lets you provide the context value.
* `SomeContext.Consumer` is an alternative way to read context.

---

### `SomeContext` Provider {/*provider*/}

[Documentation for Provider]

#### Props {/*provider-props*/}

---

### `SomeContext.Consumer` {/*consumer*/}

[Documentation for Consumer]

#### Props {/*consumer-props*/}

---

Writing Patterns

Opening Lines by Page Type

---

Parameter Patterns

Simple parameter:

* `paramName`: Description of what it does.

Optional parameter:

* **optional** `paramName`: Description of what it does.

Parameter with special function behavior:

* `initialState`: The value you want the state to be initially. It can be a value of any type, but there is a special behavior for functions. This argument is ignored after the initial render.
  * If you pass a function as `initialState`, it will be treated as an _initializer function_. It should be pure, should take no arguments, and should return a value of any type.

Callback parameter with sub-parameters:

* `subscribe`: A function that takes a single `callback` argument and subscribes it to the store. When the store changes, it should invoke the provided `callback`. The `subscribe` function should return a function that cleans up the subscription.

Nested options object:

* **optional** `options`: An object with options for this React root.
  * **optional** `onCaughtError`: Callback called when React catches an error in an Error Boundary.
  * **optional** `onUncaughtError`: Callback called when an error is thrown and not caught.
  * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by `useId`.

---

Return Value Patterns

Single value return:

`hookName` returns the current value. The value will be the same as `initialValue` during the first render.

Array return (numbered list):

`useState` returns an array with exactly two values:

1. The current state. During the first render, it will match the `initialState` you have passed.
2. The [`set` function](#setstate) that lets you update the state to a different value and trigger a re-render.

Object return (bulleted list):

`createElement` returns a React element object with a few properties:

* `type`: The `type` you have passed.
* `props`: The `props` you have passed except for `ref` and `key`.
* `ref`: The `ref` you have passed. If missing, `null`.
* `key`: The `key` you have passed, coerced to a string. If missing, `null`.

Promise return:

`prerender` returns a Promise:
- If rendering is successful, the Promise will resolve to an object containing:
  - `prelude`: a [Web Stream](MDN-link) of HTML.
  - `postponed`: a JSON-serializable object for resumption.
- If rendering fails, the Promise will be rejected.

Wrapped function return:

`cache` returns a cached version of `fn` with the same type signature. It does not call `fn` in the process.

When calling `cachedFn` with given arguments, it first checks if a cached result exists. If cached, it returns the result. If not, it calls `fn`, stores the result, and returns it.

---

Caveats Patterns

Standard Hook caveat (almost always first for Hooks):

* `useXxx` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it.

Stable identity caveat (for returned functions):

* The `set` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire.

Strict Mode caveat:

* In Strict Mode, React will **call your render function twice** in order to help you find accidental impurities. This is development-only behavior and does not affect production.

Caveat with code example:

* It's not recommended to _suspend_ a render based on a store value returned by `useSyncExternalStore`. For example, the following is discouraged:

const selectedProductId = useSyncExternalStore(...); const data = use(fetchItem(selectedProductId)) // X Don't suspend based on store value

Canary caveat:

* <CanaryBadge /> If you want to pass `ref` to a Fragment, you can't use the `<>...</>` syntax.

---

Troubleshooting Patterns

Heading format (first person problem statements):

### I've updated the state, but logging gives me the old value {/*old-value*/}

### My initializer or updater function runs twice {/*runs-twice*/}

### I want to read the latest state from a callback {/*read-latest-state*/}

Error message format:

### I'm getting an error: "Too many re-renders" {/*too-many-rerenders*/}

### I'm getting an error: "Rendered more hooks than during the previous render" {/*more-hooks*/}

Lint error format:

### I'm getting a lint error: "[exact error message]" {/*lint-error-slug*/}

Problem-solution structure: 1. State the problem with code showing the issue 2. Explain why it happens 3. Provide the solution with corrected code 4. Link to Learn section for deeper understanding

---

Code Comment Conventions

For code comment conventions (wrong/right, legacy/recommended, server/client labeling, bundle size annotations), invoke /docs-sandpack.

---

Link Description Patterns

---

Component Patterns

For comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, Deprecated, RSC, Canary, Diagram, Code Steps), invoke /docs-components.

For Sandpack-specific patterns and code style, invoke /docs-sandpack.

Reference-Specific Component Rules

Component placement in Reference pages:

• <RSC> goes before <Intro> at top of page
• <Deprecated> goes after <Intro> for page-level deprecation
• <Deprecated> goes after method heading for method-level deprecation
• <Canary> wrapper goes inline within <Intro>
• <CanaryBadge /> appears in headings, props lists, and caveats

Troubleshooting-specific components:

• Use first-person problem headings
• Cross-reference Pitfall IDs when relevant

Callout spacing:

• Never place consecutive Pitfalls or consecutive Notes
• Combine related warnings into one with titled subsections, or separate with prose/code
• Consecutive DeepDives OK for multi-part explorations
• See /docs-components Callout Spacing Rules

---

Content Principles

Intro Section

• One sentence, ~15 words max - State what the Hook does, not how it works
• ✅ "useEffectEvent is a React Hook that lets you separate events from Effects."
• ❌ "useEffectEvent is a React Hook that lets you extract non-reactive logic from your Effects into a reusable function called an Effect Event."

Reference Code Example

• Show just the API call (5-10 lines), not a full component
• Move full component examples to Usage section

Usage Section Structure

1. First example: Core mental model - Show the canonical use case with simplest concrete example 2. Subsequent examples: Canonical use cases - Name the why (e.g., "Avoid reconnecting to external systems"), show a concrete how

• Prefer broad canonical use cases over multiple narrow concrete examples
• The section title IS the teaching - "When would I use this?" should be answered by the heading

What to Include vs. Exclude

• Never document past bugs or fixed issues
• Include edge cases most developers will encounter
• Exclude niche edge cases (e.g., this binding, rare class patterns)

Caveats Section

• Include rules the linter enforces or that cause immediate errors
• Include fundamental usage restrictions
• Exclude implementation details unless they affect usage
• Exclude repetition of things explained elsewhere
• Keep each caveat to one sentence when possible

Troubleshooting Section

• Error headings only: "I'm getting an error: '[message]'" format
• Never document past bugs - if it's fixed, it doesn't belong here
• Focus on errors developers will actually encounter today

DeepDive Content

• Goldilocks principle - Deep enough for curious developers, short enough to not overwhelm
• Answer "why is it designed this way?" - not exhaustive technical details
• Readers who skip it should miss nothing essential for using the API
• If the explanation is getting long, you're probably explaining too much

---

Domain-Specific Guidance

Hooks

Returned function documentation:

• Document setter/dispatch functions as separate ### sections
• Use generic names: "set functions" not "setCount"
• Include stable identity caveat for returned functions

Dependency array documentation:

• List what counts as reactive values
• Explain when dependencies are ignored
• Link to removing effect dependencies guide

Recipes usage:

• Group related examples with meaningful titleText
• Each recipe has brief intro, Sandpack, and <Solution />

---

Components

Props documentation:

• Use #### Props instead of #### Parameters
• Mark optional props with **optional** prefix
• Use <CanaryBadge /> inline for canary-only props

JSX syntax in titles/headings:

• Frontmatter title: title: <Suspense>
• Reference heading: ` ### <Suspense> {/*suspense*/} `

---

React-DOM

Common props linking:

`<input>` supports all [common element props.](/reference/react-dom/components/common#common-props)

Props categorization:

• Controlled vs uncontrolled props grouped separately
• Form-specific props documented with action patterns
• MDN links for standard HTML attributes

Environment-specific notes:

<Note>

This API is specific to Node.js. Environments with [Web Streams](MDN-link), like Deno and modern edge runtimes, should use [`renderToReadableStream`](/reference/react-dom/server/renderToReadableStream) instead.

</Note>

Progressive enhancement:

• Document benefits for users without JavaScript
• Explain Server Function + form action integration
• Show hidden form field and .bind() patterns

---

RSC

RSC banner (before Intro): Always place <RSC> component before <Intro> for Server Component-only APIs.

Serialization type lists: When documenting Server Function arguments, list supported types:

Supported types for Server Function arguments:

* Primitives
	* [string](MDN-link)
	* [number](MDN-link)
* Iterables containing serializable values
	* [Array](MDN-link)
	* [Map](MDN-link)

Notably, these are not supported:
* React elements, or [JSX](/learn/writing-markup-with-jsx)
* Functions (other than Server Functions)

Bundle size comparisons:

• Show "Not included in bundle" for server-only imports
• Annotate client bundle sizes with gzip: // 35.9K (11.2K gzipped)

---

Compiler

Configuration page structure:

• Type (union type or interface)
• Default value
• Options/Valid values with descriptions

Directive documentation:

• Placement requirements are critical
• Mode interaction tables showing combinations
• "Use sparingly" + "Plan for removal" patterns for escape hatches

Library author guides:

• Audience-first intro
• Benefits/Why section
• Numbered step-by-step setup

---

ESLint

Rule Details section:

• Explain "why" not just "what"
• Focus on React's underlying assumptions
• Describe consequences of violations

Invalid/Valid sections:

• Standard intro: "Examples of [in]correct code for this rule:"
• Use X emoji for invalid, checkmark for valid
• Show inline comments explaining the violation

Configuration options:

• Show shared settings (preferred)
• Show rule-level options (backward compatibility)
• Note precedence when both exist

---

Edge Cases

For deprecated, canary, and version-specific component patterns (placement, syntax, examples), invoke /docs-components.

Quick placement rules:

• <Deprecated> after <Intro> for page-level, after heading for method-level
• <Canary> wrapper inline in Intro, <CanaryBadge /> in headings/props/caveats
• Version notes use <Note> with "Starting in React 19..." pattern

Removed APIs on index pages:

## Removed APIs {/*removed-apis*/}

These APIs were removed in React 19:

* [`render`](https://18.react.dev/reference/react-dom/render): use [`createRoot`](/reference/react-dom/client/createRoot) instead.

Link to previous version docs (18.react.dev) for removed API documentation.

---

Critical Rules

1. Heading IDs required: ## Title {/*title-id*/} (lowercase, hyphens) 2. Sandpack main file needs `export default` 3. Active file syntax: `js src/File.js active 4. Error headings in Troubleshooting: Use ### I'm getting an error: "[message]" {/*id*/} 5. Section dividers (`---`) required between headings (see Section Dividers below) 6. InlineToc required: Always include <InlineToc /> after Intro 7. Consistent parameter format: Use * \paramName\: description with **optional** prefix for optional params 8. Numbered lists for array returns: When hooks return arrays, use numbered lists in Returns section 9. Generic names for returned functions: Use "set functions" not "setCount" 10. Props vs Parameters: Use #### Props for Components (Type B), #### Parameters for Hooks/APIs (Type A) 11. RSC placement: <RSC> component goes before <Intro>, not after 12. Canary markers: Use <Canary> wrapper inline in Intro, <CanaryBadge /> in headings/props 13. Deprecated placement: <Deprecated> goes after <Intro> for page-level, after heading for method-level 14. Code comment emojis: Use X for wrong, checkmark for correct in code examples 15. No consecutive Pitfalls/Notes: Combine into one component with titled subsections, or separate with prose/code (see /docs-components)

For component heading level conventions (DeepDive, Pitfall, Note, Recipe headings), see /docs-components.

Section Dividers

Use --- horizontal rules to visually separate major sections:

• After `<InlineToc />` - Before ## Reference heading
• Between API subsections - Between different function/hook definitions (e.g., between useState() and set functions)
• Before `## Usage` - Separates API reference from examples
• Before `## Troubleshooting` - Separates content from troubleshooting
• Between EVERY Usage subsections - When switching to a new major use case

Always have a blank line before and after ---.

Section ID Conventions