Coding Guidelines

Guidelines for React/Next.js development focusing on testability, Server Components, and proper architecture. Each guideline file contains principles, code examples, and anti-patterns to avoid.

Quick Reference

• •Server Components & Data Fetching → server-components.md
• •Testability & Props Control → testability.md
• •useEffect Guidelines & Dependencies → useeffect-guidelines.md
• •Architecture & Patterns → architecture.md
• •Functional Style (Immutable/FP/Inference) → functional-style.md
• •Test Guidelines (Vitest/RTL) → test-guidelines.md
• •Storybook Guidelines → storybook-guidelines.md

When to Use What

Server Components

When: Writing server-side data fetching or async components Read: server-components.md

Key topics:

• •Server Component Pattern (async/await, Suspense)
• •Promise Handling (.then().catch() vs try-catch)
• •When NOT to use "use client"

Testability

When: Writing "use client" components, useEffect, or event handlers Read: testability.md

Key topics:

• •Props Control (all states controllable via props)
• •Closure Variable Dependencies (extract to pure functions)
• •Conditional Branch Extraction (JSX → components, useEffect → pure functions)

useEffect Guidelines & Dependencies

When: Deciding whether to use useEffect, managing dependencies, or avoiding unnecessary re-renders Read: useeffect-guidelines.md

Key topics:

• •When you DON'T need useEffect (data transformation, expensive calculations)
• •When you DO need useEffect (external system synchronization)
• •Event handlers vs Effects decision framework
• •Data fetching patterns and race conditions
• •Separating reactive and non-reactive logic
• •Managing dependencies (updater functions, useEffectEvent, avoiding objects/functions)
• •Reactive values and dependency array rules
• •Never suppress the exhaustive-deps linter

Architecture

When: Creating files, functions, or organizing code structure Read: architecture.md

Key topics:

• •Directory Structure (component collocation, naming)
• •Entity/Gateway Pattern (data types and fetching)
• •Function Extraction (action-based design)
• •Presenter Pattern (conditional text)

Test Guidelines

When: Creating or updating test code during Phase 2 (Testing & Stories) Read: test-guidelines.md

Key topics:

• •AAA Pattern (Arrange-Act-Assert)
• •Test Structure (describe/test descriptions in Japanese)
• •Coverage Standards (branch coverage, exception paths)
• •React Testing Library best practices
• •Snapshot testing guidelines

Storybook Guidelines

When: Creating Storybook stories for components with conditional rendering during Phase 2 (Testing & Stories) Read: storybook-guidelines.md

Key topics:

• •Story Creation Rules (conditional branching focus)
• •Meta Configuration (minimal setup)
• •Event Handlers (fn() usage)
• •Anti-patterns to avoid

Core Principles

1. •Server Component First: Default to Server Components, use "use client" only when necessary
2. •Props Control Everything: All UI states must be controllable via props for testability
3. •Pure Functions: Extract all conditional logic from useEffect/handlers
4. •No Closure Dependencies: Pass all variables as function arguments
5. •Entity/Gateway Pattern: Separate data types (entity) from fetching logic (gateway)
6. •Collocate Functions: Place function files at same level as components, no utils/ directories

Quick Decision Tree

Are you writing a component?
├─ Does it need interactivity? (onClick, useState, useEffect)
│  ├─ YES → "use client" required
│  │  ├─ Using useEffect?
│  │  │  └─ Read: useeffect-guidelines.md (Do you really need it? + Managing dependencies)
│  │  └─ Read: testability.md
│  └─ NO → Server Component (default)
│     └─ Read: server-components.md
│
├─ Does it fetch data?
│  └─ Read: server-components.md + architecture.md (Entity/Gateway)
│
├─ Are you organizing files/functions?
│  └─ Read: architecture.md (Directory Structure)
│
├─ Are you writing tests?
│  └─ Read: test-guidelines.md (AAA Pattern, Coverage, RTL)
│
└─ Are you creating Storybook stories?
   └─ Read: storybook-guidelines.md (Conditional Branching, Story Structure)