docs-writer-reference

リファレンスページの執筆

クイックリファレンス

ページタイプの判断ツリー

1. Hook ですか？ Type A（Hook/Function） を使用します
2. React コンポーネント（<Something>）ですか？ Type B（Component） を使用します
3. コンパイラーの設定オプションですか？ Type C（Configuration） を使用します
4. ディレクティブ（'use something'）ですか？ Type D（Directive） を使用します
5. ESLint ルールですか？ Type E（ESLint Rule） を使用します
6. 複数の API を一覧表示するものですか？ Type F（Index/Category） を使用します

コンポーネントの選択

コンポーネントの選択とパターンについては、/docs-components を呼び出します。

---

文体とスタイル

文体： 権威ある技術リファレンスの執筆者 トーン： 正確、包括的、中立的

トーン、大文字表記、専門用語、文章のパターンについては、/docs-voice を呼び出します。

推奨事項：

• 1 行の説明から始めます：「useState は、次のことを可能にする React Hook です……」
• すべての API に Parameters、Returns、Caveats のセクションを含めます
• ほとんどの開発者が遭遇するエッジケースを説明します
• 主要なセクションの間に区切り線を入れます
• 「以下の例をもっと見る」へのリンクを含めます
• 断定的に書き、曖昧な表現は避けます。「これは……向けに設計されています」とし、「これは問題を避けるのに役立ちます」とはしません
• 利点ではなく事実を述べます。「コールバックは常に最新の値にアクセスします」とし、「古いクロージャを避けるのに役立ちます」とはしません
• 簡潔で意味のある名前を使います。onSomething より onEvent や onTick を使用します

禁止事項：

• InlineToc コンポーネントを省略しないでください
• エラーケースや注意事項を省略しないでください
• 会話調の表現を使わないでください
• 教え方とリファレンスを混在させないでください（それは Learn の役割です）
• 過去のバグや修正済みの問題を説明しないでください
• ニッチなエッジケース（例：this のバインディング、まれなクラスパターン）を含めないでください
• 「なぜこれを使うのか」を説明する文言を加えないでください。Usage セクションの例がその役割を果たします
• 例外：Pitfall と DeepDive の補足では、やや会話調の表現を使用できます

---

ページテンプレート

Type A：Hook/Function

使用する場面： React Hook と単独の関数（useState、useEffect、memo、lazy など）を説明する場合

---
title: hookName
---

<Intro>

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

```js
const result = hookName(arg)

---

リファレンス {/reference/}

hookName(arg) {/hookname/}

コンポーネントのトップレベルで hookName を呼び出すと、次のことができます……

[signature example with annotations]

以下の例をもっと見る。

Parameters {/parameters/}

• arg：引数の説明。

Returns {/returns/}

戻り値の説明。

Caveats {/caveats/}

• 使用上の重要な注意事項。

---

使用方法 {/usage/}

一般的なユースケース {/common-use-case/}

Sandpack の例を使った説明……

---

トラブルシューティング {/troubleshooting/}

よくある問題 {/common-problem/}

解決方法……

---

### Type B: Component

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

```mdx
---
title: <ComponentName>
---

<Intro>

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

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

---

リファレンス {/reference/}

<ComponentName> {/componentname/}

[コンポーネントの目的と動作]

Props {/props/}

• propName：prop の説明……
• 任意 optionalProp：省略可能な prop の説明……

Caveats {/caveats/}

• [このコンポーネント固有の注意事項]

**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/}

optionName {/optionname/}

[オプションの目的の説明]

Type {/type/}

'value1' | 'value2' | 'value3'

Default value {/default-value/}

'value1'

Options {/options/}

• 'value1'（デフォルト）：説明
• 'value2'：説明
• 'value3'：説明

Caveats {/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/}

'use directive' {/use-directive/}

[場所]の先頭に 'use directive' を追加して、[操作]を実行します。

Caveats {/caveats/}

• 'use directive' は必ず先頭に記述します……
• ディレクティブはバッククォートではなく、シングルクォートまたはダブルクォートで記述する必要があります。
• [その他の配置や構文に関する注意事項]

**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/}

このルールに準拠したコードの例：

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

トラブルシューティング {/troubleshooting/}

[問題の説明] {/problem-slug/}

[解決方法]

オプション {/options/}

[該当する場合は設定オプション]

**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);
}

---

独自の [Type] {/your-own-type/}

JavaScript 関数として独自のものを定義することもできます。

**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*/}

主な規則：

• 水平線（---）でメインのフックと返される関数を区切ります
• 見出し ID にはプレフィックスを含めます：{/*setstate-parameters*/} と {/*parameters*/} のようにします
• 汎用的な名前を使います：「setCount」ではなく「set functions」

---

複合戻り値オブジェクト

使用する場面： 関数が複数のプロパティ／メソッドを持つオブジェクトを返す場合（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*/}

---

記述パターン

ページタイプ別の冒頭文

ページタイプ	パターン	例
フック	`hookName` is a React Hook that lets you [action].	「useState is a React Hook that lets you add a state variable to your 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.」
設定	The `optionName` option [controls/specifies/determines] [what].	「The target option specifies which React version the compiler generates code for.」
ディレクティブ	`'directive'` [marks/opts/prevents] [what] for [purpose].	「'use server' marks a function as callable from the client.」
ESLint ルール	Validates that [condition].	「Validates that dependency arrays for React hooks contain all necessary dependencies.」

---

パラメータのパターン

単純なパラメータ：

* `paramName`: Description of what it does.

省略可能なパラメータ：

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

特殊な関数の動作を持つパラメータ：

* `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.

サブパラメータを持つコールバックパラメータ：

* `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.

ネストされたオプションオブジェクト：

* **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`.

---

戻り値のパターン

単一の値を返す場合：

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

配列を返す場合（番号付きリスト）：

`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.

オブジェクトを返す場合（箇条書きリスト）：

`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 を返す場合：

`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.

ラップされた関数を返す場合：

`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.

---

注意事項のパターン

標準的なフックの注意事項（ほとんどの場合、フックの最初に記載）：

* `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.

安定した同一性に関する注意事項（返される関数向け）：

* 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 に関する注意事項：

* 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.

コード例を含む注意事項：

* 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.

---

トラブルシューティングのパターン

見出しの形式（一人称の問題文）：

### 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*/}

エラーメッセージの形式：

### 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 エラーの形式：

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

問題と解決策の構成：

1. 問題を述べ、問題がわかるコードを示します
2. なぜ発生するのかを説明します
3. 修正したコードで解決策を示します
4. 詳しく理解するための Learn セクションへのリンクを記載します

---

コードコメントの規則

コードコメントの規則（誤り／正しい例、レガシー／推奨、サーバー／クライアントのラベル、バンドルサイズの注釈）については、/docs-sandpack を呼び出してください。

---

リンクの説明パターン

パターン	例
「lets you」＋動作	「memo lets you skip re-rendering when props are unchanged.」
「declares」＋対象	「useState declares a state variable that you can update directly.」
「reads」＋対象	「useContext reads and subscribes to a context.」
「connects」＋対象	「useEffect connects a component to an external system.」
「Used with」	「Used with useContext.」
「Similar to」	「Similar to useTransition.」

---

コンポーネントのパターン

包括的な MDX コンポーネントのパターン（Note、Pitfall、DeepDive、Recipes、Deprecated、RSC、Canary、Diagram、Code Steps）については、/docs-components を呼び出してください。

Sandpack 固有のパターンとコードスタイルについては、/docs-sandpack を呼び出してください。

リファレンス固有のコンポーネントルール

リファレンスページでのコンポーネントの配置：

• <RSC> はページの先頭で <Intro> より前に配置します
• ページ全体の非推奨を示す <Deprecated> は <Intro> の後に配置します
• メソッド単位の非推奨を示す <Deprecated> はメソッドの見出しの後に配置します
• <Canary> のラッパーは <Intro> 内にインラインで配置します
• <CanaryBadge /> は見出し、props リスト、注意事項に配置します

トラブルシューティング固有のコンポーネント：

• 一人称の問題見出しを使います
• 該当する場合は、Pitfall ID を相互参照します

コールアウトの間隔：

• Pitfall や Note を連続して配置しないでください
• 関連する警告は、タイトル付きの小見出しを含む1つの項目にまとめるか、間に説明文やコードを挟んで分けます
• 複数パートにわたる解説では、DeepDive を連続して配置できます
• /docs-components のコールアウトの間隔ルールを参照してください

---

コンテンツの原則

Intro セクション

• 1文、最大約15語 — Hook の仕組みではなく、何をするかを説明します
• ✅ 「useEffectEvent は、イベントを Effects から分離できる React Hook です。」
• ❌ 「useEffectEvent は、Effects からリアクティブでないロジックを抽出し、Effect Event と呼ばれる再利用可能な関数にできる React Hook です。」

リファレンスのコード例

• 完全なコンポーネントではなく、API 呼び出しだけを示します（5〜10行）
• 完全なコンポーネントの例は Usage セクションに移します

Usage セクションの構成

1. 最初の例：基本的なメンタルモデル — 最もシンプルで具体的な例を使い、代表的なユースケースを示します
2. 以降の例：代表的なユースケース — 理由（例：「外部システムへの再接続を避ける」）を示し、具体的な方法を説明します
   • 複数の限定的で具体的な例より、幅広く応用できる代表的なユースケースを優先します
   • セクションのタイトル自体が説明の役割を果たします。「これはいつ使うのか？」という問いには、見出しで答えます

含める内容と除外する内容

• 過去のバグや修正済みの問題については決して説明しません
• 多くの開発者が遭遇するエッジケースは含めます
• 限定的なエッジケース（例：this のバインディング、まれなクラスのパターン）は除外します

Caveats セクション

• リンターが強制するルールや、即座にエラーを引き起こすルールを含めます
• 基本的な使用上の制約を含めます
• 使用方法に影響しない限り、実装の詳細は除外します
• ほかの場所で説明した内容の繰り返しは除外します
• 可能な限り、各注意事項は1文にまとめます

Troubleshooting セクション

• エラーの見出しのみを記載し、「エラーが発生しています：『[message]』」の形式にします
• 過去のバグについては決して説明しません。修正済みであれば、ここには含めません
• 現在、開発者が実際に遭遇するエラーに焦点を当てます

DeepDive の内容

• ゴルディロックスの原則 — 興味のある開発者が満足できる深さを保ちつつ、読み手を圧倒しない簡潔さを心がけます
• 網羅的な技術詳細ではなく、「なぜこのように設計されているのか」に答えます
• 読み飛ばしても API の利用に不可欠な情報を見落とさないようにします
• 説明が長くなってきたら、詳しく説明しすぎている可能性があります

---

ドメイン固有のガイダンス

Hooks

返される関数のドキュメント：

• setter 関数や dispatch 関数は、個別の ### セクションとして説明します
• 「setCount」ではなく「set 関数」のような汎用的な名前を使います
• 返される関数の同一性が安定していることに関する注意事項を含めます

依存配列のドキュメント：

• リアクティブな値に該当するものを列挙します
• 依存関係が無視される場合を説明します
• Effect の依存関係を削除する方法のガイドにリンクします

Recipes の使い方：

• 関連する例を、意味のある titleText を付けてグループ化します
• 各レシピには、短い導入、Sandpack、<Solution /> を含めます

---

Components

Props のドキュメント：

• #### Parameters ではなく #### Props を使います
• オプションの props には **optional** を接頭辞として付けます
• canary 版のみで使える props には、インラインで <CanaryBadge /> を使います

タイトル／見出しでの JSX 構文：

• Frontmatter のタイトル：title: <Suspense>
• リファレンスの見出し：### `<Suspense>` {/*suspense*/}

React-DOM

共通の props のリンク付け：

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

props の分類：

• 制御された props と制御されていない props を別々にグループ化します
• フォーム固有の props はアクションのパターンとともに説明します
• 標準の HTML 属性には MDN へのリンクを付けます

環境固有の注意事項：

<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>

プログレッシブエンハンスメント：

• JavaScript を使用しないユーザーにとっての利点を説明します
• Server Function とフォームアクションの連携について説明します
• hidden フォームフィールドと .bind() のパターンを示します

---

RSC

RSC バナー（Intro の前）： Server Component 専用 API では、必ず <RSC> コンポーネントを <Intro> の前に配置します。

シリアライズ可能な型の一覧： Server Function の引数を説明する場合は、サポートされている型を列挙します。

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)

バンドルサイズの比較：

• サーバー専用のインポートには「バンドルに含まれません」と表示します
• クライアントバンドルのサイズには gzip 圧縮後のサイズを注記します：// 35.9K (11.2K gzipped)

---

Compiler

設定ページの構成：

• 型（ユニオン型またはインターフェース）
• デフォルト値
• 説明付きのオプション／有効な値

ディレクティブの説明：

• 配置要件は重要です
• 組み合わせを示すモードの相互作用テーブル
• 例外的な回避策には「使用は控えめに」＋「削除を計画する」のパターンを適用します

ライブラリー作成者向けガイド：

• 読者を優先した導入
• 利点／理由のセクション
• 番号付きの手順形式による設定方法

---

ESLint

Rule Details セクション：

• 「何をするか」だけでなく、「なぜ必要か」を説明します
• React の根底にある前提に焦点を当てます
• 違反した場合の影響を説明します

Invalid／Valid セクション：

• 標準の導入文：「このルールに対する正しい／誤ったコードの例：」
• 誤りには X の絵文字、正しい例にはチェックマークを使用します
• 違反箇所を説明するインラインコメントを示します

設定オプション：

• 共通設定を示します（推奨）
• ルールレベルのオプションを示します（後方互換性のため）
• 両方を指定した場合の優先順位を記載します

---

例外的なケース

非推奨、canary、バージョン固有のコンポーネントパターン（配置、構文、例）については、/docs-components を呼び出してください。

配置に関する簡単なルール：

• ページレベルでは <Intro> の後、メソッドレベルでは見出しの後に <Deprecated> を配置します
• Intro 内には <Canary> ラッパーをインラインで、見出し／props／注意点には <CanaryBadge /> を配置します
• バージョンに関する注記には、「React 19 以降では……」というパターンの <Note> を使用します

インデックスページの削除済み API：

## 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.

削除済み API のドキュメントへのリンクには、以前のバージョンのドキュメント（18.react.dev）を使用します。

---

重要なルール

1. 見出し ID は必須です： ## Title {/*title-id*/}（小文字、ハイフン区切り）
2. Sandpack のメインファイルには export default が必要です
3. アクティブファイルの構文： ```js src/File.js active
4. Troubleshooting のエラー見出し： ### I'm getting an error: "[message]" {/*id*/} を使用します
5. 見出し間にはセクション区切り（---）が必要です（「セクション区切り」を参照）
6. InlineToc は必須です： Intro の後には必ず <InlineToc /> を含めます
7. パラメーター形式を統一します： * \paramName`: descriptionを使用し、任意のパラメーターにはoptional` を前置します
8. 配列を返す場合は番号付きリストを使用します： フックが配列を返す場合、Returns セクションでは番号付きリストを使用します
9. 返される関数には汎用的な名前を使用します： 「setCount」ではなく「set functions」を使用します
10. Props と Parameters： コンポーネント（Type B）には #### Props、フック／API（Type A）には #### Parameters を使用します
11. RSC の配置： <RSC> コンポーネントは <Intro> の後ではなく、前に配置します
12. Canary マーカー： Intro 内には <Canary> ラッパーをインラインで、見出し／props には <CanaryBadge /> を使用します
13. Deprecated の配置： ページレベルでは <Intro> の後、メソッドレベルでは見出しの後に <Deprecated> を配置します
14. コードコメントの絵文字： コード例では、誤りに X、正しい例にチェックマークを使用します
15. Pitfall／Note を連続させないでください： タイトル付きのサブセクションを含む 1 つのコンポーネントにまとめるか、文章／コードで区切ります（/docs-components を参照）

コンポーネントの見出しレベルの規則（DeepDive、Pitfall、Note、Recipe の見出し）については、/docs-components を参照してください。

セクション区切り

主要なセクションを視覚的に区切るには、--- の水平線を使用します。

• <InlineToc /> の後 - ## Reference 見出しの前
• API サブセクション間 - 異なる関数／フックの定義の間（例：useState() と set functions の間）
• ## Usage の前 - API リファレンスと例を区切ります
• ## Troubleshooting の前 - トラブルシューティングの前にコンテンツを区切ります
• すべての Usage サブセクション間 - 主要なユースケースが切り替わる箇所

--- の前後には必ず空行を入れます。

セクション ID の規約

セクション	ID 形式
メイン関数	{/*functionname*/}
返される関数	{/*setstate*/}, {/*dispatch*/}
返される関数のサブセクション	{/*setstate-parameters*/}
トラブルシューティング項目	{/*problem-description-slug*/}
落とし穴	{/*pitfall-description*/}
詳細解説	{/*deep-dive-topic*/}