From b047bad5a33fff8bade9a01a5161c33a0ab65b3e Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Sun, 8 Feb 2026 12:24:04 -0500 Subject: [PATCH 1/8] Add .worktrees/ to .gitignore Prevent worktree contents from being tracked. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index ff88094dee0..92626a1e63a 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,6 @@ public/rss.xml # claude local settings .claude/*.local.* .claude/react/ + +# worktrees +.worktrees/ From 233a4c2a50534b5d2015be8ac2e6e1684e567415 Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Sun, 8 Feb 2026 13:03:20 -0500 Subject: [PATCH 2/8] feat(react-expert): add web search exception for error code research --- .claude/skills/react-expert/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/react-expert/SKILL.md b/.claude/skills/react-expert/SKILL.md index 5ebcdee37d1..bee418bffc0 100644 --- a/.claude/skills/react-expert/SKILL.md +++ b/.claude/skills/react-expert/SKILL.md @@ -38,7 +38,7 @@ This skill produces exhaustive documentation research on any React API or concep 8. **TypeScript Types** - Note discrepancies with Flow 9. **Current react.dev docs** - Baseline (not trusted as complete) -**No web search** - No Stack Overflow, blog posts, or web searches. GitHub API via `gh` CLI is allowed. +**No web search** - No Stack Overflow, blog posts, or web searches. GitHub API via `gh` CLI is allowed. **Exception:** Error code research mode (see below) explicitly allows web search to understand real-world developer pain points. ## Workflow From 073e35b13d5d53c160d3881619f367d266ee5523 Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Sun, 8 Feb 2026 13:04:49 -0500 Subject: [PATCH 3/8] feat(react-expert): add error code research mode with 7 agents --- .claude/skills/react-expert/SKILL.md | 300 +++++++++++++++++++++++++++ 1 file changed, 300 insertions(+) diff --git a/.claude/skills/react-expert/SKILL.md b/.claude/skills/react-expert/SKILL.md index bee418bffc0..4e8e610e30b 100644 --- a/.claude/skills/react-expert/SKILL.md +++ b/.claude/skills/react-expert/SKILL.md @@ -314,6 +314,306 @@ Replace spaces in topic with hyphens (e.g., "suspense boundaries" → "suspense- - Issue #: - <url> ``` +## Error Code Research Mode + +When invoked with `error` as the first argument, this skill switches to error-code research mode. + +### Invocation + +``` +/react-expert error 310 +/react-expert error 31 +``` + +### Step 1: Setup React Repo + +Same as standard mode (see above). + +### Step 2: Look Up Error Message + +Fetch the error codes JSON: + +```bash +curl -s https://raw-githubusercontent-com-gh.computerqwq.top/facebook/react/main/scripts/error-codes/codes.json | python3 -c "import sys,json; codes=json.load(sys.stdin); print(codes.get('<CODE>', 'NOT FOUND'))" +``` + +Record the exact message template. Note the number of `%s` placeholders. + +### Step 3: Dispatch 7 Parallel Research Agents + +Spawn these agents IN PARALLEL using the Task tool. Each agent receives the skepticism preamble plus the error message template. + +| Agent | subagent_type | Focus | +|-------|---------------|-------| +| error-source-finder | Explore | Find all throw sites for this error code | +| test-explorer | Explore | Find tests that trigger this error | +| source-explorer | Explore | Find related warnings and dev-mode messages | +| pr-researcher | Explore | Find PRs that introduced or modified this error | +| issue-hunter | Explore | Find GitHub issues reporting this error | +| web-researcher | general-purpose | Web search for real-world developer struggles | +| git-historian | Explore | Find commits related to this error | + +### Step 4: Error-Specific Agent Prompts + +#### error-source-finder +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files. + +Your task: Find every location in the React source that throws error code <CODE>. + +1. Search: grep -rn "<CODE>" .claude/react/packages/*/src/ (look for the error code in error/invariant calls) +2. Also search: grep -rn "error(<CODE>" .claude/react/packages/*/src/ +3. For each throw site, document: + - The exact file path and line number + - The condition (if statement / validation) that triggers the throw + - What each %s argument resolves to at that call site + - The function/module context +4. Determine which throw sites correspond to user-facing scenarios vs internal invariants + +Format: +## Throw Sites +### Site 1: <file>:<line> +**Condition:** <the if/validation check> +**Arguments:** %s1 = <value>, %s2 = <value> +**Context:** <function name and what it does> +**User-facing:** Yes/No +``` + +#### test-explorer (error mode) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files. + +Your task: Find test files in .claude/react that trigger or test error <CODE>. + +1. Search for the error code in test files: grep -rn "<CODE>" .claude/react/packages/*/src/__tests__/ +2. Search for the error message text in tests +3. For each test, extract: + - The test description (describe/it blocks) + - The code that triggers the error + - How the test asserts the error is thrown +4. Report findings with exact file paths and line numbers + +Format: +## Test File: <path> +### Test: "<test description>" +```javascript +<exact code from test> +``` +**Triggers error by:** <what the test does to cause the error> +``` + +#### source-explorer (error mode) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in source files. + +Your task: Find related warnings and dev-mode messages for error <CODE>. + +1. Find the file(s) where error <CODE> is thrown +2. Look for related console.error/console.warn calls near the throw sites +3. Check if there's a different dev-mode message that provides more detail +4. Document any related error codes thrown from the same functions + +Format: +## Dev-Mode Messages +| Message | Relationship to Error <CODE> | Source | +|---------|------------------------------|--------| +| "<message>" | <how it relates> | <file:line> | + +## Related Error Codes +| Code | Message | Thrown From Same Location? | +|------|---------|--------------------------| +``` + +#### web-researcher (error mode only) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +IMPORTANT: Web search IS allowed for error code research. Use WebSearch and WebFetch tools. + +Your task: Find how real developers encounter and struggle with this error. + +1. Search for: + - "react error <CODE>" + - "react minified error <CODE>" + - "Minified React error #<CODE>" + - The error message text itself +2. Look at Stack Overflow, GitHub Discussions, Reddit r/reactjs, and blog posts +3. For each relevant result, document: + - What the developer was trying to do + - What caused the error in their case + - What solution worked + - What they struggled with or found confusing +4. Identify the most common real-world scenarios + +Format: +## Real-World Occurrences +### Source: <URL> +**Scenario:** <what the developer was doing> +**Cause:** <what triggered the error> +**Solution:** <what fixed it> +**Confusion:** <what they found confusing> + +## Summary of Common Patterns +1. Most common cause: ... +2. Second most common: ... +3. What confuses people most: ... +``` + +#### pr-researcher (error mode) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in PRs. + +Your task: Find PRs related to error <CODE>. + +1. Run: gh pr list -R facebook/react --search "error <CODE>" --state all --limit 20 --json number,title,url +2. Also search: gh pr list -R facebook/react --search "<key words from error message>" --state all --limit 20 --json number,title,url +3. For promising PRs, read details: gh pr view <number> -R facebook/react +4. Look for: when this error was introduced, why, any changes to its behavior + +Format: +## Key PRs +### PR #<number>: <title> +**URL:** <url> +**Summary:** <what it introduced/changed about this error> +**Design Rationale:** <why this error exists> +``` + +#### issue-hunter (error mode) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in issues. + +Your task: Find GitHub issues where users report error <CODE>. + +1. Search: gh issue list -R facebook/react --search "error <CODE>" --state all --limit 20 --json number,title,url +2. Search: gh issue list -R facebook/react --search "Minified React error #<CODE>" --state all --limit 20 --json number,title,url +3. Search: gh issue list -R reactjs/react.dev --search "error <CODE>" --state all --limit 20 --json number,title,url +4. For each issue, identify: + - What triggered the error + - The resolution + - Common misunderstandings + +Format: +## Issues +### Issue #<number>: <title> +**Repo:** <repo> +**Trigger:** <what caused the error> +**Resolution:** <how it was resolved> +**Misunderstanding:** <if applicable> +``` + +#### git-historian (error mode) +``` +You are researching React error code <CODE>. +Error message: "<MESSAGE>" + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in git history. + +Your task: Find commits related to error <CODE>. + +1. Run: cd .claude/react && git log --all --grep="<CODE>" --oneline -30 +2. Also: cd .claude/react && git log --all --grep="<key words from message>" --oneline -30 +3. For significant commits, read full message: git show <hash> --stat +4. Look for when this error was introduced, modified, or discussed + +Format: +## Key Commits +### <short hash> - <subject> +**Date:** <date> +**Context:** <why this change was made> +**Impact:** <what changed about this error> +``` + +### Step 5: Synthesize Results + +After all agents complete, combine findings into a research document. Prioritize: +1. Throw sites and their conditions +2. Real-world causes (ordered by frequency from web research) +3. Developer pain points and confusion +4. Design rationale + +**DO NOT add information from your own knowledge.** Only include what agents found. + +### Step 6: Save Output + +Write to `.claude/research/error-<CODE>.md` + +### Error Research Output Template + +```markdown +# React Error Research: Error #<CODE> + +> Generated by /react-expert error <CODE> on YYYY-MM-DD +> Error message: "<message template>" +> Sources: React repo (commit <hash>), N throw sites, M issues, K web results + +## Error Message + +<exact template> + +**Placeholders:** %s1 = <what it represents>, %s2 = ... + +## Throw Sites + +[From error-source-finder] + +## Common Real-World Causes + +[Synthesized from all agents — ordered by frequency from web research] + +1. **<cause>** — seen in N Stack Overflow posts, M GitHub issues +2. **<cause>** — seen in ... + +## Developer Pain Points + +[From web-researcher — what confuses people] + +## Dev-Mode Messages + +[From source-explorer — messages shown in development that differ from production] + +## Test Coverage + +[From test-explorer — how React's own tests exercise this error] + +## Design Decisions + +[From git-historian and pr-researcher — why this error exists] + +## GitHub Issues + +[From issue-hunter] + +## Source Links + +### Commits +- <hash>: <description> + +### Pull Requests +- PR #<number>: <title> - <url> + +### Issues +- Issue #<number>: <title> - <url> + +### Web Sources +- <url>: <brief description> +``` + ## Common Mistakes to Avoid 1. **Trusting prior knowledge** - If you "know" something about the API, find the source evidence anyway From 8b68ded4ce520829425f346a3fbaeaebea4ad25f Mon Sep 17 00:00:00 2001 From: Rick Hanlon <rickhanlonii@meta.com> Date: Sun, 8 Feb 2026 13:06:59 -0500 Subject: [PATCH 4/8] feat(react-expert): update checklist and common mistakes for error mode --- .claude/skills/react-expert/SKILL.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.claude/skills/react-expert/SKILL.md b/.claude/skills/react-expert/SKILL.md index 4e8e610e30b..69cfe465b63 100644 --- a/.claude/skills/react-expert/SKILL.md +++ b/.claude/skills/react-expert/SKILL.md @@ -618,18 +618,20 @@ Write to `.claude/research/error-<CODE>.md` 1. **Trusting prior knowledge** - If you "know" something about the API, find the source evidence anyway 2. **Generating example code** - Every code example must come from an actual source file -3. **Skipping agents** - All 6 agents must run; each provides unique perspective +3. **Skipping agents** - All 6 agents must run (7 in error-code mode); each provides unique perspective 4. **Summarizing without sources** - Every claim needs a file:line or PR/issue reference -5. **Using web search** - No Stack Overflow, no blog posts, no social media +5. **Using web search** - No Stack Overflow, no blog posts, no social media (exception: error-code research mode) ## Verification Checklist Before finalizing the research document: - [ ] React repo is at `.claude/react` with known commit hash -- [ ] All 6 agents were spawned in parallel +- [ ] All 6 agents were spawned in parallel (7 in error-code mode) - [ ] Every code example has a source file reference - [ ] Warnings/errors table has source locations - [ ] No claims made without source evidence - [ ] Discrepancies between Flow/TS types documented - [ ] Source links section is complete +- [ ] (Error mode only) Web researcher found real-world occurrences +- [ ] (Error mode only) Throw sites documented with conditions and %s arguments From 87382b295021279f7af6789ddc4b6f6f6beee0dd Mon Sep 17 00:00:00 2001 From: Rick Hanlon <rickhanlonii@meta.com> Date: Sun, 8 Feb 2026 13:09:23 -0500 Subject: [PATCH 5/8] feat: add docs-writer-error skill for React error pages --- .claude/skills/docs-writer-error/SKILL.md | 294 ++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 .claude/skills/docs-writer-error/SKILL.md diff --git a/.claude/skills/docs-writer-error/SKILL.md b/.claude/skills/docs-writer-error/SKILL.md new file mode 100644 index 00000000000..843c18bdb60 --- /dev/null +++ b/.claude/skills/docs-writer-error/SKILL.md @@ -0,0 +1,294 @@ +--- +name: docs-writer-error +description: Use when writing or editing error pages in src/content/errors/. Provides error page structure, research workflow, and troubleshooting guide conventions. +--- + +# Error Page Writer + +## Persona + +**Voice:** Empathetic debugger helping a frustrated developer +**Tone:** Direct, diagnostic, reassuring — never condescending + +## Voice & Style + +For tone, capitalization, jargon, and prose patterns, invoke `/docs-voice`. + +**Key tone adjustments for error pages:** +- Developers arrive mid-debugging. Be concise and actionable. +- Lead with "what happened" before "how to fix it." +- Avoid "simply", "just", "easy" — the developer is already stuck. +- Use "you" to address the reader directly. +- Name the specific React behavior that triggered the error. + +## Workflow: Research First + +Before writing any error page, you must research the error thoroughly. + +### Step 1: Invoke `/react-expert` in Error Code Mode + +Run: +``` +/react-expert error <CODE> +``` + +This dispatches 7 parallel research agents that will: +- Find every throw site for this error in the React source +- Find test files that trigger this error +- Search GitHub issues for user reports of this error +- Search the web for Stack Overflow questions, blog posts, and forum discussions to understand how real developers encounter and struggle with this error +- Find PRs and commits for design context + +Wait for the research to complete. The output will be saved to `.claude/research/error-<CODE>.md`. + +### Step 2: Analyze the Research + +From the research output, determine: +1. **What the error message means** — use throw site conditions and `%s` argument context +2. **Common causes** — prioritize by: + - Frequency in web search results and GitHub issues (most common first) + - What developers struggle with most (from web-researcher findings) + - What scenarios are reproducible in Sandpack +3. **Developer pain points** — what confuses people about this error? Use this to inform the prose explanation. +4. **Related docs** — which existing react.dev pages help explain the concepts involved + +### Step 3: Write the Error Page + +Place the file at `src/content/errors/{code}.md`. Use the template below. + +## Page Template + +```mdx +<Intro> + +In the minified production build of React, we avoid sending down full error messages in order to reduce the number of bytes sent over the wire. + +</Intro> + +We highly recommend using the development build locally when debugging your app since it tracks additional debug info and provides helpful warnings about potential problems in your apps, but if you encounter an exception while using the production build, this page will reassemble the original error message. + +The full text of the error you just encountered is: + +<ErrorDecoder /> + +## What This Error Means {/*what-this-error-means*/} + +[Plain-language explanation. 1-3 paragraphs.] + +## Common Causes {/*common-causes*/} + +### Cause Title {/*cause-title*/} + +[Explanation. 1-2 paragraphs.] + +Here is an example of code that would trigger this error: + +<Sandpack> + +` ` `js +// 🔴 This will cause the error +[problem code] +` ` ` + +</Sandpack> + +[Transition sentence explaining the fix:] + +<Sandpack> + +` ` `js +// ✅ Fixed: [what changed] +[solution code] +` ` ` + +</Sandpack> + +## Related Documentation {/*related-documentation*/} + +- [Link text](/path/to/page) +``` + +## Section Guidelines + +### Boilerplate (Required, Verbatim) + +The `<Intro>` block, the paragraph about development builds, and `<ErrorDecoder />` must appear on every error page exactly as shown. Do not modify, reword, or omit any part. + +### What This Error Means + +- Open with: "This error occurs when [condition]." +- Explain what React was doing when it threw the error. +- If the message has `%s` placeholders, explain what each represents. +- Do not repeat the error message text — `<ErrorDecoder />` already shows it. +- Name the specific React concept involved. +- Address the developer pain points found in research — if people commonly misunderstand why this error happens, address that confusion directly. + +**Opening sentence patterns:** + +| Category | Pattern | +|----------|---------| +| Hooks | "This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks)." | +| Rendering | "This error occurs when React encounters [invalid element/children] during rendering." | +| Hydration | "This error occurs when the HTML generated by the server does not match what the client renders." | +| Server Components | "This error occurs when a value that is not serializable is passed from a Server Component to a Client Component." | +| Suspense | "This error occurs when a component suspends during rendering without a `<Suspense>` boundary to catch it." | + +### Common Causes + +- 1-4 causes per page. Most errors have 2-3. +- Each cause gets its own `###` heading under `## Common Causes`. +- Each cause must include: prose explanation, Problem Sandpack, Solution Sandpack. +- Use descriptive headings: "Calling a Hook inside a condition", not "Cause 1". +- **Order by real-world frequency**: Use web search and GitHub issue data from the research to determine which causes developers hit most often. The most common cause goes first. +- **Address real confusion**: If the research shows developers struggle to understand why a particular pattern causes this error, explain it clearly in the prose. + +### Related Documentation + +- At least one link. Bulleted list. +- Learn pages for concepts, Reference pages for APIs. +- Format API links with backticks: [`useState`](/reference/react/useState) + +## Sandpack Guidelines + +For general Sandpack conventions, invoke `/docs-sandpack`. + +### Problem Sandpacks + +- Mark problematic code with `// 🔴`. +- Keep examples minimal — only code needed to trigger the error. +- Must have `export default` in main file. +- **Base examples on real-world patterns** found in web search results — not abstract/contrived scenarios. + +### Solution Sandpacks + +- Mark fix with `// ✅ Fixed: [description]`. +- Change only what's necessary. Don't refactor unrelated code. +- Must be runnable and produce a visible result. + +### Transition Sentences Between Pairs + +- "To fix this, move the Hook call to the top level of your component:" +- "Instead, convert the value to a supported type before passing it:" +- "To fix this, wrap the component in a `<Suspense>` boundary:" + +### When Sandpack Can't Reproduce the Error + +Use plain fenced code blocks instead: + +```mdx +This error occurs during server rendering. The problematic pattern looks like this: + +` ` `js +// 🔴 This will cause the error during server rendering +function App() { + return <ServerComponent data={new Map()} />; +} +` ` ` +``` + +### Multi-File Sandpacks + +Use when the error involves component relationships (parent/child, server/client): + +```mdx +<Sandpack> + +` ` `js src/App.js active +import Child from './Child'; + +export default function App() { + // 🔴 Passing an invalid value to Child + return <Child data={Symbol('test')} />; +} +` ` ` + +` ` `js src/Child.js +export default function Child({ data }) { + return <div>{String(data)}</div>; +} +` ` ` + +</Sandpack> +``` + +## Component Usage + +For full component patterns, invoke `/docs-components`. + +| Component | Use For | +|-----------|---------| +| `<Note>` | Edge cases, version differences | +| `<Pitfall>` | A fix that introduces a new common mistake | +| `<DeepDive>` | Why React enforces this rule (optional) | +| `<ConsoleBlock level="error">` | Showing exact console output | + +Use `<ConsoleBlock>` sparingly — only when the dev-mode message differs meaningfully from the production error. + +## Handling Error Variations + +### Errors That Are React Bugs + +For errors saying "This is likely caused by a bug in React": + +```mdx +## What This Error Means {/*what-this-error-means*/} + +This error indicates an internal invariant violation in React. It is not caused by your application code. + +If you encounter this error, please [file an issue](https://github.com/facebook/react/issues/new?template=bug_report.md) on the React GitHub repository with a reproduction. +``` + +Keep these pages minimal. Do not invent common causes. + +### Server-Specific Errors + +- Note that these errors occur on the server, not in the browser. +- Use plain code blocks instead of Sandpack. +- Link to RSC documentation. + +### Hooks Errors + +- Always link to [Rules of Hooks](/reference/rules/rules-of-hooks). +- Common causes: conditional calls, calls in loops, calls outside components, mismatched React versions. + +## Do's and Don'ts + +**Do:** +- Invoke `/react-expert error <CODE>` before writing +- Use the boilerplate verbatim +- Explain what `%s` placeholders represent +- Show problem code before solution (problem-first) +- Keep Sandpack examples minimal +- Order causes by real-world frequency (from research) +- Base examples on real developer scenarios (from web search) +- Address common developer confusion (from research) +- Link to at least one related docs page +- Use `// 🔴` and `// ✅` markers + +**Don't:** +- Write error pages without research +- Add frontmatter to error pages +- Modify the boilerplate text +- Repeat the error message in prose +- Include more than 4 causes +- Use contrived/abstract examples when real-world patterns exist +- Use `<Challenges>`, `<Recipes>`, `<YouWillLearn>`, or `<Recap>` +- Use `<InlineToc />` +- Use `---` section dividers +- Place consecutive `<Pitfall>` or `<Note>` without separating prose + +## Critical Rules + +1. **Research first:** Always invoke `/react-expert error <CODE>` before writing. +2. **Boilerplate is sacred:** `<Intro>`, dev build paragraph, and `<ErrorDecoder />` must appear verbatim. +3. **No frontmatter:** Error pages have no YAML frontmatter. +4. **All headings require IDs:** `## Title {/*title-id*/}` in kebab-case. +5. **Problem-first Sandpacks:** Show broken code before the fix. +6. **One pair per cause:** Each cause gets one problem + one solution Sandpack (or plain code blocks). +7. **Real-world examples:** Base Sandpack examples on patterns from web research, not contrived scenarios. +8. **No consecutive callouts:** Separate `<Pitfall>`/`<Note>` with prose. +9. **Minimal examples:** Keep Sandpack files under 50 lines when possible. +10. **File naming:** `{code}.md` in `src/content/errors/`. +11. **`export default` required:** All Sandpack main files need it. + +For component patterns, invoke `/docs-components`. For Sandpack patterns, invoke `/docs-sandpack`. From 023a39248ce804de8ab2363ac5739459b070681d Mon Sep 17 00:00:00 2001 From: Rick Hanlon <rickhanlonii@meta.com> Date: Sun, 8 Feb 2026 13:10:59 -0500 Subject: [PATCH 6/8] feat: auto-suggest docs-writer-error for error page content --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CLAUDE.md b/CLAUDE.md index 3a081e6d517..a88556acd32 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,6 +43,7 @@ src/ When editing files in `src/content/`, the appropriate skill will be auto-suggested: - `src/content/learn/` - Learn page structure and tone - `src/content/reference/` - Reference page structure and tone +- `src/content/errors/` - Error page structure and tone For MDX components (DeepDive, Pitfall, Note, etc.), invoke `/docs-components`. For Sandpack code examples, invoke `/docs-sandpack`. From d9364e20d7e4b7ac1becb38945b6f642f65e80d6 Mon Sep 17 00:00:00 2001 From: Rick Hanlon <rickhanlonii@meta.com> Date: Sun, 8 Feb 2026 17:25:33 -0500 Subject: [PATCH 7/8] feat: add error 321 page, update skill rules, and add error reviewer --- .claude/skills/docs-writer-error/SKILL.md | 68 ++++++++---- .claude/skills/review-docs/SKILL.md | 1 + src/content/errors/321.md | 127 ++++++++++++++++++++++ 3 files changed, 173 insertions(+), 23 deletions(-) create mode 100644 src/content/errors/321.md diff --git a/.claude/skills/docs-writer-error/SKILL.md b/.claude/skills/docs-writer-error/SKILL.md index 843c18bdb60..4a4e0560f6b 100644 --- a/.claude/skills/docs-writer-error/SKILL.md +++ b/.claude/skills/docs-writer-error/SKILL.md @@ -61,19 +61,31 @@ Place the file at `src/content/errors/{code}.md`. Use the template below. ```mdx <Intro> -In the minified production build of React, we avoid sending down full error messages in order to reduce the number of bytes sent over the wire. +This page explains this React error and common ways to fix it. </Intro> -We highly recommend using the development build locally when debugging your app since it tracks additional debug info and provides helpful warnings about potential problems in your apps, but if you encounter an exception while using the production build, this page will reassemble the original error message. - -The full text of the error you just encountered is: +The full text of the error is: <ErrorDecoder /> +<Note> + +In the minified production build of React, full error messages are replaced with short codes to reduce bundle size. We recommend using the development build when debugging, as it includes additional warnings and debug information. + +</Note> + ## What This Error Means {/*what-this-error-means*/} -[Plain-language explanation. 1-3 paragraphs.] +[One-line opener ending with `:` — identifies the error condition]: + +` ` `js {N} +[Minimal code showing the broken pattern, with // 🔴 marker and line highlight] +` ` ` + +[1-2 paragraphs explaining why this causes an error — what React was doing, what concept is involved.] + +[See the examples below for common causes and how to fix them.](#common-causes) ## Common Causes {/*common-causes*/} @@ -103,6 +115,8 @@ Here is an example of code that would trigger this error: </Sandpack> +[Optional: 1-2 sentences of supplementary context, e.g., related patterns or edge cases.] + ## Related Documentation {/*related-documentation*/} - [Link text](/path/to/page) @@ -112,32 +126,39 @@ Here is an example of code that would trigger this error: ### Boilerplate (Required, Verbatim) -The `<Intro>` block, the paragraph about development builds, and `<ErrorDecoder />` must appear on every error page exactly as shown. Do not modify, reword, or omit any part. +The `<Intro>` block, `<ErrorDecoder />`, and the `<Note>` about minified builds must appear on every custom error page exactly as shown in the template. Do not modify, reword, or omit any part. The intro leads with purpose ("explains this React error and common ways to fix it"), and the minification context is placed in a `<Note>` after the error decoder. The generic error page (`generic.md`) uses a different boilerplate — this skill only covers custom error pages. ### What This Error Means -- Open with: "This error occurs when [condition]." -- Explain what React was doing when it threw the error. -- If the message has `%s` placeholders, explain what each represents. -- Do not repeat the error message text — `<ErrorDecoder />` already shows it. -- Name the specific React concept involved. -- Address the developer pain points found in research — if people commonly misunderstand why this error happens, address that confusion directly. +**Structure (in order):** +1. Open with "This error occurs when [condition]:" — one sentence, ending with a colon, linking to relevant docs if applicable. +2. Show a plain fenced code block (not Sandpack) with the broken pattern — use `{N}` line highlighting on the problematic line and a `// 🔴` comment marker. +3. Explain why this causes an error in 1-2 paragraphs — what React was doing, what concept is involved. Address the developer pain points found in research — if people commonly misunderstand why this error happens, address that confusion directly. +4. End with: `[See the examples below for common causes and how to fix them.](#common-causes)` + +**Rules:** +- The code block is a quick illustrative snippet, NOT an interactive Sandpack — it gives the reader instant visual recognition of the broken pattern. +- Use line highlighting (`{N}`) to point to the exact problematic line. +- The `// 🔴` marker comment in the code block may reference the error concept (e.g., `// 🔴 Invalid Hook call!`). +- If the message has `%s` placeholders, explain what each represents in the explanation paragraphs. +- The explanation paragraphs follow the code — "show, then explain." +- Keep the code block minimal (under ~15 lines) — just enough to show the pattern. -**Opening sentence patterns:** +**Opening sentence patterns** (all end with `:`): | Category | Pattern | |----------|---------| -| Hooks | "This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks)." | -| Rendering | "This error occurs when React encounters [invalid element/children] during rendering." | -| Hydration | "This error occurs when the HTML generated by the server does not match what the client renders." | -| Server Components | "This error occurs when a value that is not serializable is passed from a Server Component to a Client Component." | -| Suspense | "This error occurs when a component suspends during rendering without a `<Suspense>` boundary to catch it." | +| Hooks | "This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks):" | +| Rendering | "This error occurs when React encounters [invalid element/children] during rendering:" | +| Hydration | "This error occurs when the HTML generated by the server does not match what the client renders:" | +| Server Components | "This error occurs when a value that is not serializable is passed from a Server Component to a Client Component:" | +| Suspense | "This error occurs when a component suspends during rendering without a `<Suspense>` boundary to catch it:" | ### Common Causes - 1-4 causes per page. Most errors have 2-3. - Each cause gets its own `###` heading under `## Common Causes`. -- Each cause must include: prose explanation, Problem Sandpack, Solution Sandpack. +- Each cause must include: prose explanation, and either a Problem/Solution Sandpack pair, or plain code blocks. Build/configuration causes may use diagnostic commands and fix snippets instead. - Use descriptive headings: "Calling a Hook inside a condition", not "Cause 1". - **Order by real-world frequency**: Use web search and GitHub issue data from the research to determine which causes developers hit most often. The most common cause goes first. - **Address real confusion**: If the research shows developers struggle to understand why a particular pattern causes this error, explain it clearly in the prose. @@ -156,6 +177,7 @@ For general Sandpack conventions, invoke `/docs-sandpack`. - Mark problematic code with `// 🔴`. - Keep examples minimal — only code needed to trigger the error. +- When the error being documented also triggers a lint rule, include `// eslint-disable-next-line` to suppress the lint error so the Sandpack demonstrates the runtime behavior. - Must have `export default` in main file. - **Base examples on real-world patterns** found in web search results — not abstract/contrived scenarios. @@ -255,7 +277,7 @@ Keep these pages minimal. Do not invent common causes. **Do:** - Invoke `/react-expert error <CODE>` before writing -- Use the boilerplate verbatim +- Use the boilerplate verbatim (intro, error decoder, minification note) - Explain what `%s` placeholders represent - Show problem code before solution (problem-first) - Keep Sandpack examples minimal @@ -268,7 +290,7 @@ Keep these pages minimal. Do not invent common causes. **Don't:** - Write error pages without research - Add frontmatter to error pages -- Modify the boilerplate text +- Modify the boilerplate text (intro, error decoder, or minification note) - Repeat the error message in prose - Include more than 4 causes - Use contrived/abstract examples when real-world patterns exist @@ -280,11 +302,11 @@ Keep these pages minimal. Do not invent common causes. ## Critical Rules 1. **Research first:** Always invoke `/react-expert error <CODE>` before writing. -2. **Boilerplate is sacred:** `<Intro>`, dev build paragraph, and `<ErrorDecoder />` must appear verbatim. +2. **Boilerplate is sacred:** `<Intro>`, `<ErrorDecoder />`, and the minification `<Note>` must appear verbatim on every custom error page. 3. **No frontmatter:** Error pages have no YAML frontmatter. 4. **All headings require IDs:** `## Title {/*title-id*/}` in kebab-case. 5. **Problem-first Sandpacks:** Show broken code before the fix. -6. **One pair per cause:** Each cause gets one problem + one solution Sandpack (or plain code blocks). +6. **One pair per cause:** Each cause gets one problem + one solution Sandpack (or plain code blocks). Exception: build/configuration causes (e.g., duplicate packages) may use diagnostic commands and fix snippets instead of a strict problem/solution pair. 7. **Real-world examples:** Base Sandpack examples on patterns from web research, not contrived scenarios. 8. **No consecutive callouts:** Separate `<Pitfall>`/`<Note>` with prose. 9. **Minimal examples:** Keep Sandpack files under 50 lines when possible. diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md index 61a6a0e05c6..04ddf7fe687 100644 --- a/.claude/skills/review-docs/SKILL.md +++ b/.claude/skills/review-docs/SKILL.md @@ -9,6 +9,7 @@ Run these tasks in parallel for the given file(s). Each agent checks different a - [ ] Ask docs-reviewer agent to review {files} with docs-writer-learn (only for files in src/content/learn/). - [ ] Ask docs-reviewer agent to review {files} with docs-writer-reference (only for files in src/content/reference/). - [ ] Ask docs-reviewer agent to review {files} with docs-writer-blog (only for files in src/content/blog/). +- [ ] Ask docs-reviewer agent to review {files} with docs-writer-error (only for files in src/content/errors/). - [ ] Ask docs-reviewer agent to review {files} with docs-voice (all documentation files). - [ ] Ask docs-reviewer agent to review {files} with docs-components (all documentation files). - [ ] Ask docs-reviewer agent to review {files} with docs-sandpack (files containing Sandpack examples). diff --git a/src/content/errors/321.md b/src/content/errors/321.md new file mode 100644 index 00000000000..e0bfcb16d88 --- /dev/null +++ b/src/content/errors/321.md @@ -0,0 +1,127 @@ +<Intro> + +This page explains this React error and common ways to fix it. + +</Intro> + +The full text of the error is: + +<ErrorDecoder /> + +<Note> + +In the minified production build of React, full error messages are replaced with short codes to reduce bundle size. We recommend using the development build when debugging, as it includes additional warnings and debug information. + +</Note> + +## What This Error Means {/*what-this-error-means*/} + +This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks): + +```js {4} +export default function Counter() { + function handleClick() { + // 🔴 Invalid Hook call! + const [count, setCount] = useState(0); + setCount(count + 1); + } + + return <button onClick={handleClick}>Click me</button>; +} +``` + +You can only call Hooks at the top level of a function component or a custom Hook. React tracks Hooks by associating them with the component that is currently rendering. When you call a Hook and no component is rendering, React cannot associate the Hook with a component, and throws this error. + +The most common cause is calling a Hook outside a function component. For example, inside an event handler, a class component, or a regular function. Another common cause is having **multiple copies of React** loaded in your app, which is a build configuration problem, not a coding mistake. + +[See the examples below for common causes and how to fix them.](#common-causes) + +## Common Causes {/*common-causes*/} + +### Calling a Hook outside the body of a function component {/*calling-a-hook-outside-the-body-of-a-function-component*/} + +React requires you to call Hooks at the top level of a function component or a custom Hook—not inside event handlers, nested functions, or class components. + +Here is an example of code that would trigger this error: + +<Sandpack> + +```js {expectedErrors: {'react-compiler': [7]}} +import { useState } from 'react'; + +export default function Counter() { + function handleClick() { + // 🔴 useState is called inside an event handler, not the component body + // eslint-disable-next-line react-hooks/rules-of-hooks + const [count, setCount] = useState(0); + setCount(count + 1); + } + + return <button onClick={handleClick}>Click me</button>; +} +``` + +</Sandpack> + +To fix this, move the Hook call to the top level of your component: + +<Sandpack> + +```js +import { useState } from 'react'; + +// ✅ Fixed: useState is called at the top level of the component +export default function Counter() { + const [count, setCount] = useState(0); + + function handleClick() { + setCount(count + 1); + } + + return <button onClick={handleClick}>Count: {count}</button>; +} +``` + +</Sandpack> + +The same rule applies to class components—you cannot use Hooks in class components. If you need state or other React features in a class component, [convert it to a function component](/reference/react/Component#alternatives). + +### Multiple copies of React in your app {/*multiple-copies-of-react*/} + +If your project uses a monorepo, `npm link`, or a third-party package that bundles its own copy of React, you can end up with two separate copies of React loaded at the same time. When this happens, the copy of React that your component uses is different from the copy that `react-dom` uses, and Hooks break because React can't track them across copies. + +To check if this is your problem, run the following from your project root: + +```bash +npm ls react +``` + +If you see more than one entry for `react`, you have duplicate copies. You can also add a temporary log to confirm. Add this at the top of your component file: + +```js +import React from 'react'; +console.log(React === window.React); // false means duplicates +``` + +If you're using webpack, you can fix this by adding a resolve alias in your webpack config: + +```js +// webpack.config.js +module.exports = { + resolve: { + alias: { + react: require.resolve('react'), + 'react-dom': require.resolve('react-dom'), + }, + }, +}; +``` + +If you're using Vite, add a similar alias in your Vite config. For other bundlers, consult their documentation on how to configure module aliases. + +## Related Documentation {/*related-documentation*/} + +- [Rules of Hooks](/reference/rules/rules-of-hooks) +- [`useState`](/reference/react/useState) +- [Your First Component](/learn/your-first-component) +- [Reusing Logic with Custom Hooks](/learn/reusing-logic-with-custom-hooks) From f41564a1a296a4ccda3ccd48795ab0fc8f53c07b Mon Sep 17 00:00:00 2001 From: Rick Hanlon <rickhanlonii@meta.com> Date: Sun, 8 Feb 2026 17:34:38 -0500 Subject: [PATCH 8/8] Ooops --- src/content/errors/321.md | 127 -------------------------------------- 1 file changed, 127 deletions(-) delete mode 100644 src/content/errors/321.md diff --git a/src/content/errors/321.md b/src/content/errors/321.md deleted file mode 100644 index e0bfcb16d88..00000000000 --- a/src/content/errors/321.md +++ /dev/null @@ -1,127 +0,0 @@ -<Intro> - -This page explains this React error and common ways to fix it. - -</Intro> - -The full text of the error is: - -<ErrorDecoder /> - -<Note> - -In the minified production build of React, full error messages are replaced with short codes to reduce bundle size. We recommend using the development build when debugging, as it includes additional warnings and debug information. - -</Note> - -## What This Error Means {/*what-this-error-means*/} - -This error occurs when a Hook is called in a way that violates the [Rules of Hooks](/reference/rules/rules-of-hooks): - -```js {4} -export default function Counter() { - function handleClick() { - // 🔴 Invalid Hook call! - const [count, setCount] = useState(0); - setCount(count + 1); - } - - return <button onClick={handleClick}>Click me</button>; -} -``` - -You can only call Hooks at the top level of a function component or a custom Hook. React tracks Hooks by associating them with the component that is currently rendering. When you call a Hook and no component is rendering, React cannot associate the Hook with a component, and throws this error. - -The most common cause is calling a Hook outside a function component. For example, inside an event handler, a class component, or a regular function. Another common cause is having **multiple copies of React** loaded in your app, which is a build configuration problem, not a coding mistake. - -[See the examples below for common causes and how to fix them.](#common-causes) - -## Common Causes {/*common-causes*/} - -### Calling a Hook outside the body of a function component {/*calling-a-hook-outside-the-body-of-a-function-component*/} - -React requires you to call Hooks at the top level of a function component or a custom Hook—not inside event handlers, nested functions, or class components. - -Here is an example of code that would trigger this error: - -<Sandpack> - -```js {expectedErrors: {'react-compiler': [7]}} -import { useState } from 'react'; - -export default function Counter() { - function handleClick() { - // 🔴 useState is called inside an event handler, not the component body - // eslint-disable-next-line react-hooks/rules-of-hooks - const [count, setCount] = useState(0); - setCount(count + 1); - } - - return <button onClick={handleClick}>Click me</button>; -} -``` - -</Sandpack> - -To fix this, move the Hook call to the top level of your component: - -<Sandpack> - -```js -import { useState } from 'react'; - -// ✅ Fixed: useState is called at the top level of the component -export default function Counter() { - const [count, setCount] = useState(0); - - function handleClick() { - setCount(count + 1); - } - - return <button onClick={handleClick}>Count: {count}</button>; -} -``` - -</Sandpack> - -The same rule applies to class components—you cannot use Hooks in class components. If you need state or other React features in a class component, [convert it to a function component](/reference/react/Component#alternatives). - -### Multiple copies of React in your app {/*multiple-copies-of-react*/} - -If your project uses a monorepo, `npm link`, or a third-party package that bundles its own copy of React, you can end up with two separate copies of React loaded at the same time. When this happens, the copy of React that your component uses is different from the copy that `react-dom` uses, and Hooks break because React can't track them across copies. - -To check if this is your problem, run the following from your project root: - -```bash -npm ls react -``` - -If you see more than one entry for `react`, you have duplicate copies. You can also add a temporary log to confirm. Add this at the top of your component file: - -```js -import React from 'react'; -console.log(React === window.React); // false means duplicates -``` - -If you're using webpack, you can fix this by adding a resolve alias in your webpack config: - -```js -// webpack.config.js -module.exports = { - resolve: { - alias: { - react: require.resolve('react'), - 'react-dom': require.resolve('react-dom'), - }, - }, -}; -``` - -If you're using Vite, add a similar alias in your Vite config. For other bundlers, consult their documentation on how to configure module aliases. - -## Related Documentation {/*related-documentation*/} - -- [Rules of Hooks](/reference/rules/rules-of-hooks) -- [`useState`](/reference/react/useState) -- [Your First Component](/learn/your-first-component) -- [Reusing Logic with Custom Hooks](/learn/reusing-logic-with-custom-hooks)