1# React Best Practices
2 
3A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
4 
5## Structure
6 
7- `rules/` - Individual rule files (one per rule)
8  - `_sections.md` - Section metadata (titles, impacts, descriptions)
9  - `_template.md` - Template for creating new rules
10  - `area-description.md` - Individual rule files
11- `src/` - Build scripts and utilities
12- `metadata.json` - Document metadata (version, organization, abstract)
13- __`AGENTS.md`__ - Compiled output (generated)
14- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
15 
16## Getting Started
17 
181. Install dependencies:
19   ```bash
20   pnpm install
21   ```
22 
232. Build AGENTS.md from rules:
24   ```bash
25   pnpm build
26   ```
27 
283. Validate rule files:
29   ```bash
30   pnpm validate
31   ```
32 
334. Extract test cases:
34   ```bash
35   pnpm extract-tests
36   ```
37 
38## Creating a New Rule
39 
401. Copy `rules/_template.md` to `rules/area-description.md`
412. Choose the appropriate area prefix:
42   - `async-` for Eliminating Waterfalls (Section 1)
43   - `bundle-` for Bundle Size Optimization (Section 2)
44   - `server-` for Server-Side Performance (Section 3)
45   - `client-` for Client-Side Data Fetching (Section 4)
46   - `rerender-` for Re-render Optimization (Section 5)
47   - `rendering-` for Rendering Performance (Section 6)
48   - `js-` for JavaScript Performance (Section 7)
49   - `advanced-` for Advanced Patterns (Section 8)
503. Fill in the frontmatter and content
514. Ensure you have clear examples with explanations
525. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
53 
54## Rule File Structure
55 
56Each rule file should follow this structure:
57 
58```markdown
59---
60title: Rule Title Here
61impact: MEDIUM
62impactDescription: Optional description
63tags: tag1, tag2, tag3
64---
65 
66## Rule Title Here
67 
68Brief explanation of the rule and why it matters.
69 
70**Incorrect (description of what's wrong):**
71 
72```typescript
73// Bad code example
74```
75 
76**Correct (description of what's right):**
77 
78```typescript
79// Good code example
80```
81 
82Optional explanatory text after examples.
83 
84Reference: [Link](https://example.com)
85 
86## File Naming Convention
87 
88- Files starting with `_` are special (excluded from build)
89- Rule files: `area-description.md` (e.g., `async-parallel.md`)
90- Section is automatically inferred from filename prefix
91- Rules are sorted alphabetically by title within each section
92- IDs (e.g., 1.1, 1.2) are auto-generated during build
93 
94## Impact Levels
95 
96- `CRITICAL` - Highest priority, major performance gains
97- `HIGH` - Significant performance improvements
98- `MEDIUM-HIGH` - Moderate-high gains
99- `MEDIUM` - Moderate performance improvements
100- `LOW-MEDIUM` - Low-medium gains
101- `LOW` - Incremental improvements
102 
103## Scripts
104 
105- `pnpm build` - Compile rules into AGENTS.md
106- `pnpm validate` - Validate all rule files
107- `pnpm extract-tests` - Extract test cases for LLM evaluation
108- `pnpm dev` - Build and validate
109 
110## Contributing
111 
112When adding or modifying rules:
113 
1141. Use the correct filename prefix for your section
1152. Follow the `_template.md` structure
1163. Include clear bad/good examples with explanations
1174. Add appropriate tags
1185. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
1196. Rules are automatically sorted by title - no need to manage numbers!
120 
121## Acknowledgments
122 
123Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
124