Skip to content

Commit 73cb2aa

Browse files
chrisnojimachrisnojima
committed
fix lints
1 parent 01e7a3a commit 73cb2aa

117 files changed

Lines changed: 14044 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/vercel-react-best-practices/AGENTS.md‎

Lines changed: 3750 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/vercel-react-best-practices/README.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# React Best Practices
2+
3+
A 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+
18+
1. Install dependencies:
19+
```bash
20+
pnpm install
21+
```
22+
23+
2. Build AGENTS.md from rules:
24+
```bash
25+
pnpm build
26+
```
27+
28+
3. Validate rule files:
29+
```bash
30+
pnpm validate
31+
```
32+
33+
4. Extract test cases:
34+
```bash
35+
pnpm extract-tests
36+
```
37+
38+
## Creating a New Rule
39+
40+
1. Copy `rules/_template.md` to `rules/area-description.md`
41+
2. 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)
50+
3. Fill in the frontmatter and content
51+
4. Ensure you have clear examples with explanations
52+
5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
53+
54+
## Rule File Structure
55+
56+
Each rule file should follow this structure:
57+
58+
```markdown
59+
---
60+
title: Rule Title Here
61+
impact: MEDIUM
62+
impactDescription: Optional description
63+
tags: tag1, tag2, tag3
64+
---
65+
66+
## Rule Title Here
67+
68+
Brief 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+
82+
Optional explanatory text after examples.
83+
84+
Reference: [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+
112+
When adding or modifying rules:
113+
114+
1. Use the correct filename prefix for your section
115+
2. Follow the `_template.md` structure
116+
3. Include clear bad/good examples with explanations
117+
4. Add appropriate tags
118+
5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
119+
6. Rules are automatically sorted by title - no need to manage numbers!
120+
121+
## Acknowledgments
122+
123+
Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).

‎.agents/skills/vercel-react-best-practices/SKILL.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
name: vercel-react-best-practices
3+
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
4+
license: MIT
5+
metadata:
6+
author: vercel
7+
version: "1.0.0"
8+
---
9+
10+
# Vercel React Best Practices
11+
12+
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
13+
14+
## When to Apply
15+
16+
Reference these guidelines when:
17+
- Writing new React components or Next.js pages
18+
- Implementing data fetching (client or server-side)
19+
- Reviewing code for performance issues
20+
- Refactoring existing React/Next.js code
21+
- Optimizing bundle size or load times
22+
23+
## Rule Categories by Priority
24+
25+
| Priority | Category | Impact | Prefix |
26+
|----------|----------|--------|--------|
27+
| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
28+
| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
29+
| 3 | Server-Side Performance | HIGH | `server-` |
30+
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
31+
| 5 | Re-render Optimization | MEDIUM | `rerender-` |
32+
| 6 | Rendering Performance | MEDIUM | `rendering-` |
33+
| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
34+
| 8 | Advanced Patterns | LOW | `advanced-` |
35+
36+
## Quick Reference
37+
38+
### 1. Eliminating Waterfalls (CRITICAL)
39+
40+
- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
41+
- `async-defer-await` - Move await into branches where actually used
42+
- `async-parallel` - Use Promise.all() for independent operations
43+
- `async-dependencies` - Use better-all for partial dependencies
44+
- `async-api-routes` - Start promises early, await late in API routes
45+
- `async-suspense-boundaries` - Use Suspense to stream content
46+
47+
### 2. Bundle Size Optimization (CRITICAL)
48+
49+
- `bundle-barrel-imports` - Import directly, avoid barrel files
50+
- `bundle-dynamic-imports` - Use next/dynamic for heavy components
51+
- `bundle-defer-third-party` - Load analytics/logging after hydration
52+
- `bundle-conditional` - Load modules only when feature is activated
53+
- `bundle-preload` - Preload on hover/focus for perceived speed
54+
55+
### 3. Server-Side Performance (HIGH)
56+
57+
- `server-auth-actions` - Authenticate server actions like API routes
58+
- `server-cache-react` - Use React.cache() for per-request deduplication
59+
- `server-cache-lru` - Use LRU cache for cross-request caching
60+
- `server-dedup-props` - Avoid duplicate serialization in RSC props
61+
- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
62+
- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
63+
- `server-serialization` - Minimize data passed to client components
64+
- `server-parallel-fetching` - Restructure components to parallelize fetches
65+
- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
66+
- `server-after-nonblocking` - Use after() for non-blocking operations
67+
68+
### 4. Client-Side Data Fetching (MEDIUM-HIGH)
69+
70+
- `client-swr-dedup` - Use SWR for automatic request deduplication
71+
- `client-event-listeners` - Deduplicate global event listeners
72+
- `client-passive-event-listeners` - Use passive listeners for scroll
73+
- `client-localstorage-schema` - Version and minimize localStorage data
74+
75+
### 5. Re-render Optimization (MEDIUM)
76+
77+
- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
78+
- `rerender-memo` - Extract expensive work into memoized components
79+
- `rerender-memo-with-default-value` - Hoist default non-primitive props
80+
- `rerender-dependencies` - Use primitive dependencies in effects
81+
- `rerender-derived-state` - Subscribe to derived booleans, not raw values
82+
- `rerender-derived-state-no-effect` - Derive state during render, not effects
83+
- `rerender-functional-setstate` - Use functional setState for stable callbacks
84+
- `rerender-lazy-state-init` - Pass function to useState for expensive values
85+
- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
86+
- `rerender-split-combined-hooks` - Split hooks with independent dependencies
87+
- `rerender-move-effect-to-event` - Put interaction logic in event handlers
88+
- `rerender-transitions` - Use startTransition for non-urgent updates
89+
- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
90+
- `rerender-use-ref-transient-values` - Use refs for transient frequent values
91+
- `rerender-no-inline-components` - Don't define components inside components
92+
93+
### 6. Rendering Performance (MEDIUM)
94+
95+
- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
96+
- `rendering-content-visibility` - Use content-visibility for long lists
97+
- `rendering-hoist-jsx` - Extract static JSX outside components
98+
- `rendering-svg-precision` - Reduce SVG coordinate precision
99+
- `rendering-hydration-no-flicker` - Use inline script for client-only data
100+
- `rendering-hydration-suppress-warning` - Suppress expected mismatches
101+
- `rendering-activity` - Use Activity component for show/hide
102+
- `rendering-conditional-render` - Use ternary, not && for conditionals
103+
- `rendering-usetransition-loading` - Prefer useTransition for loading state
104+
- `rendering-resource-hints` - Use React DOM resource hints for preloading
105+
- `rendering-script-defer-async` - Use defer or async on script tags
106+
107+
### 7. JavaScript Performance (LOW-MEDIUM)
108+
109+
- `js-batch-dom-css` - Group CSS changes via classes or cssText
110+
- `js-index-maps` - Build Map for repeated lookups
111+
- `js-cache-property-access` - Cache object properties in loops
112+
- `js-cache-function-results` - Cache function results in module-level Map
113+
- `js-cache-storage` - Cache localStorage/sessionStorage reads
114+
- `js-combine-iterations` - Combine multiple filter/map into one loop
115+
- `js-length-check-first` - Check array length before expensive comparison
116+
- `js-early-exit` - Return early from functions
117+
- `js-hoist-regexp` - Hoist RegExp creation outside loops
118+
- `js-min-max-loop` - Use loop for min/max instead of sort
119+
- `js-set-map-lookups` - Use Set/Map for O(1) lookups
120+
- `js-tosorted-immutable` - Use toSorted() for immutability
121+
- `js-flatmap-filter` - Use flatMap to map and filter in one pass
122+
- `js-request-idle-callback` - Defer non-critical work to browser idle time
123+
124+
### 8. Advanced Patterns (LOW)
125+
126+
- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
127+
- `advanced-event-handler-refs` - Store event handlers in refs
128+
- `advanced-init-once` - Initialize app once per app load
129+
- `advanced-use-latest` - useLatest for stable callback refs
130+
131+
## How to Use
132+
133+
Read individual rule files for detailed explanations and code examples:
134+
135+
```
136+
rules/async-parallel.md
137+
rules/bundle-barrel-imports.md
138+
```
139+
140+
Each rule file contains:
141+
- Brief explanation of why it matters
142+
- Incorrect code example with explanation
143+
- Correct code example with explanation
144+
- Additional context and references
145+
146+
## Full Compiled Document
147+
148+
For the complete guide with all rules expanded: `AGENTS.md`

‎.agents/skills/vercel-react-best-practices/rules/_sections.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Sections
2+
3+
This file defines all sections, their ordering, impact levels, and descriptions.
4+
The section ID (in parentheses) is the filename prefix used to group rules.
5+
6+
---
7+
8+
## 1. Eliminating Waterfalls (async)
9+
10+
**Impact:** CRITICAL
11+
**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
12+
13+
## 2. Bundle Size Optimization (bundle)
14+
15+
**Impact:** CRITICAL
16+
**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
17+
18+
## 3. Server-Side Performance (server)
19+
20+
**Impact:** HIGH
21+
**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
22+
23+
## 4. Client-Side Data Fetching (client)
24+
25+
**Impact:** MEDIUM-HIGH
26+
**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
27+
28+
## 5. Re-render Optimization (rerender)
29+
30+
**Impact:** MEDIUM
31+
**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
32+
33+
## 6. Rendering Performance (rendering)
34+
35+
**Impact:** MEDIUM
36+
**Description:** Optimizing the rendering process reduces the work the browser needs to do.
37+
38+
## 7. JavaScript Performance (js)
39+
40+
**Impact:** LOW-MEDIUM
41+
**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
42+
43+
## 8. Advanced Patterns (advanced)
44+
45+
**Impact:** LOW
46+
**Description:** Advanced patterns for specific cases that require careful implementation.

‎.agents/skills/vercel-react-best-practices/rules/_template.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Rule Title Here
3+
impact: MEDIUM
4+
impactDescription: Optional description of impact (e.g., "20-50% improvement")
5+
tags: tag1, tag2
6+
---
7+
8+
## Rule Title Here
9+
10+
**Impact: MEDIUM (optional impact description)**
11+
12+
Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
13+
14+
**Incorrect (description of what's wrong):**
15+
16+
```typescript
17+
// Bad code example here
18+
const bad = example()
19+
```
20+
21+
**Correct (description of what's right):**
22+
23+
```typescript
24+
// Good code example here
25+
const good = example()
26+
```
27+
28+
Reference: [Link to documentation or resource](https://example.com)

0 commit comments

Comments
 (0)