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

• 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

• Server Component First: Default to Server Components, use "use client" only when necessary

• Props Control Everything: All UI states must be controllable via props for testability

• Pure Functions: Extract all conditional logic from useEffect/handlers

• No Closure Dependencies: Pass all variables as function arguments

• Entity/Gateway Pattern: Separate data types (entity) from fetching logic (gateway)

• 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)