Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack.
Reference Page Writer
Quick Reference
Page Type Decision Tree
Is it a Hook? Use Type A (Hook/Function)
Is it a React component (<Something>)? Use Type B (Component)
Is it a compiler configuration option? Use Type C (Configuration)
Is it a directive ('use something')? Use Type D (Directive)
Is it an ESLint rule? Use Type E (ESLint Rule)
Is it listing multiple APIs? Use Type F (Index/Category)
Component Selection
For component selection and patterns, invoke /docs-components.
**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
```mdx
---
title: optionName
---
<Intro>
The `optionName` option [controls/specifies/determines] [what it does].
</Intro>
```js
{
optionName: 'value' // Quick example
}
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'
```mdx
---
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].
```js {1}
function MyComponent() {
'use directive';
// ...
}
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
```mdx
---
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:
```js
// X Missing dependency
useEffect(() => {
console.log(count);
}, []); // Missing 'count'
Valid {/valid/}
Examples of correct code for this rule:
// checkmark All dependencies includeduseEffect(() => {
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
```mdx
---
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].
```js
function Example() {
const value = useHookName(args);
}
**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)
```md
### `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
Page Type
Pattern
Example
Hook
`hookName` is a React Hook that lets you [action].
"useState is a React Hook that lets you add a state variable to your component."
Component
`<ComponentName>` lets you [action].
"<Suspense> lets you display a fallback until its children have finished loading."
API
`apiName` lets you [action].
"memo lets you skip re-rendering a component when its props are unchanged."
Configuration
The `optionName` option [controls/specifies/determines] [what].
"The target option specifies which React version the compiler generates code for."
Directive
`'directive'` [marks/opts/prevents] [what] for [purpose].
"'use server' marks a function as callable from the client."
ESLint Rule
Validates that [condition].
"Validates that dependency arrays for React hooks contain all necessary dependencies."
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:
```js
const selectedProductId = useSyncExternalStore(...);
const data = use(fetchItem(selectedProductId)) // X Don't suspend based on store value
**Canary caveat:**
```md
* <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*/}
`<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
Heading IDs required:## Title {/*title-id*/} (lowercase, hyphens)
Sandpack main file needs export default
Active file syntax:```js src/File.js active
Error headings in Troubleshooting: Use ### I'm getting an error: "[message]" {/*id*/}
Section dividers (---) required between headings (see Section Dividers below)
InlineToc required: Always include <InlineToc /> after Intro
Consistent parameter format: Use * \paramName`: descriptionwithoptional` prefix for optional params
Numbered lists for array returns: When hooks return arrays, use numbered lists in Returns section
Generic names for returned functions: Use "set functions" not "setCount"
Props vs Parameters: Use #### Props for Components (Type B), #### Parameters for Hooks/APIs (Type A)
RSC placement:<RSC> component goes before <Intro>, not after
Canary markers: Use <Canary> wrapper inline in Intro, <CanaryBadge /> in headings/props
Deprecated placement:<Deprecated> goes after <Intro> for page-level, after heading for method-level
Code comment emojis: Use X for wrong, checkmark for correct in code examples
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
