frontend-patterns

Frontend Patterns

When to Apply

• Classification: feature, architecture-change (if touching UI)
• Phase: /implement (component design & build), /review (pattern compliance), /test (UI state coverage)
• Trigger: Task involves creating or modifying UI components, pages, routes, or client-side state

Conventions

Customize after /app-init: Replace these generic conventions with your project's ADR and framework-specific patterns.

Component Structure

• One component per file
• Component file name matches export name (PascalCase)
• Co-locate component-specific styles, tests, and types
• Separate page-level components from reusable UI components

Suggested Directory Pattern

src/
├── components/        # Reusable UI components (Button, Modal, Card)
│   └── <Name>/
│       ├── <Name>.tsx
│       ├── <Name>.test.tsx
│       └── index.ts
├── pages/             # Page-level components (route targets)
│   └── <PageName>/
│       ├── <PageName>.tsx
│       ├── components/ # Page-specific components (not reusable)
│       └── hooks/      # Page-specific hooks
├── hooks/             # Shared custom hooks
├── services/          # API client functions
├── stores/            # State management (if applicable)
├── types/             # Shared TypeScript types
└── utils/             # Pure utility functions

State Management Principles

• Local state first: useState/useReducer for component-specific state
• Lift state up only when sibling components need it
• Global state (store) only for truly app-wide state: auth, theme, user preferences
• Server state (API data) managed by data-fetching library (React Query, SWR, etc.) — NOT in global store
• Never duplicate server state in client store

Data Fetching

• Centralize API calls in services/ directory
• Use data-fetching hooks (React Query, SWR, or equivalent) instead of raw fetch/axios in components
• Handle loading, error, and empty states for every data-dependent component
• Implement optimistic updates for better UX where appropriate