typescript-react-patterns

Production-grade Agent Skill for TypeScript, React, and Next.js.

Korean README: README.ko.md

A structured markdown reference built for AI coding agents working on real TypeScript frontends, with especially strong coverage of React patterns and Next.js App Router architecture.

Not an npm package. Not a tutorial. A field manual for AI agents helping frontend engineers.

Before / After

Without this skill

User: "Type this API call"
Agent: const user: User = await res.json()  // ❌ no runtime validation

With this skill

User: "Type this API call"
Agent:
  const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string().email() })
  type User = z.infer<typeof userSchema>
  const user = userSchema.parse(await res.json())  // ✅ runtime + type safety

Without this skill

User: "Add loading state to this component"
Agent: const [isLoading, setIsLoading] = useState(false)
       const [error, setError] = useState(null)
       const [data, setData] = useState(null)  // ❌ boolean flags, nullable fields

With this skill

User: "Add loading state to this component"
Agent: // Uses discriminated union — impossible states are unrepresentable
  type State<T> =
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'success'; data: T }
    | { status: 'error'; error: Error }

Install

# Global (all projects)
git clone https://github.com/leejpsd/typescript-react-patterns.git ~/.claude/skills/typescript-react-patterns

# Project-only
git clone https://github.com/leejpsd/typescript-react-patterns.git .claude/skills/typescript-react-patterns

Compatible with Claude Code, Cursor, Codex, Gemini CLI, and any agent reading SKILL.md.

Structure

typescript-react-patterns/
├── SKILL.md                                ← Hub: agent rules, decision guide, checklists
├── rules/                                  ← Pattern references (loaded on demand)
│   ├── typescript-core.md                     Narrowing, unions, generics, utility types, as const, satisfies
│   ├── react-typescript-patterns.md           Props, children, events, hooks, context, forwardRef
│   ├── nextjs-typescript.md                   App Router, params, Server Actions, RSC, Edge, useOptimistic
│   ├── component-patterns.md                  Discriminated Props, compound components, modal/dialog, polymorphic
│   ├── data-fetching-and-api-types.md         Fetch, Zod, TanStack Query, Result<T,E>, pagination, error handling
│   ├── forms-and-validation.md                Form state, Zod, react-hook-form, Server Actions, multi-step forms
│   ├── state-management.md                    Local vs context vs Zustand (+ middleware) vs TanStack Query vs URL
│   ├── performance-and-accessibility.md       Memoization, effects, semantic HTML, ARIA, focus management
│   ├── debugging-checklists.md                Quick diagnosis router, serialization, null access
│   ├── code-review-rules.md                   Risk vs preference, architecture smells, comment templates
│   └── anti-patterns.md                       12 common mistakes with root causes and fixes
├── playbooks/                              ← Step-by-step debugging guides
│   ├── type-error-debugging.md                Systematic type error resolution
│   ├── hydration-issues.md                    SSR/CSR mismatch diagnosis flowchart
│   └── effect-dependency-bugs.md              Loops, stale closures, cleanups, debounce example
├── README.md
└── LICENSE

What Makes This Different

Most frontend skills stop at generic TypeScript tips. This one is intentionally stronger on React and Next.js, where coding agents most often make costly mistakes: props design, effects, state ownership, server/client boundaries, searchParams, Server Actions, hydration, serialization, and review-time architecture tradeoffs.

It is designed not just to suggest patterns, but to help an agent make safer decisions in production React and Next.js codebases.

| Feature | Typical skill | This skill | |---------|-------------|-----------| | React + Next.js depth | Limited or generic | Strong coverage of real React patterns and Next.js App Router constraints | | Pattern guidance | ✅ | ✅ | | Agent behavior rules | ❌ | ✅ What to check first, what NOT to assume | | Decision guide | ❌ | ✅ Situation → recommended pattern → file | | Debugging playbooks | ❌ | ✅ Type errors, hydration, effects, serialization | | Code review heuristics | ❌ | ✅ Risk vs preference, comment templates | | Rule classification | ❌ | ✅ [HARD RULE] / [DEFAULT] / [SITUATIONAL] | | Generation + review checklists | ❌ | ✅ Separate checklists in SKILL.md |

Each File Contains

Consistent structure across all modules:

• Scope + Consult when + See also (cross-references)
• Key rules labeled as [HARD RULE], [DEFAULT], or [SITUATIONAL]
• When to use / When NOT to use
• Examples from real frontend scenarios (forms, APIs, lists, modals)
• Counterexamples showing the wrong approach
• Tradeoffs — what you gain and what you lose
• Common bug patterns — specific failure modes
• Review checklist — copy-pasteable for PRs

Contributing

PRs welcome. Priority areas:

• Testing patterns (Vitest, Testing Library)
• Internationalization typing
• More debugging playbooks (React Query cache, Zustand devtools)
• Accessibility deep dive (ARIA patterns, focus management)
• Edge/middleware typing patterns

How to contribute a new rule

Each file should follow the template in any existing rules/*.md file:

1. Scope + Consult when + See also
2. Patterns labeled [HARD RULE] / [DEFAULT] / [SITUATIONAL]
3. Real-world examples (not toy math examples)
4. Common bug patterns
5. Review checklist

License

MIT