Prepared Docs

Prepared Docs

⌘K

    Loading navigation…

User

  1. Working On Features
  3. Components

Component Patterns

Component organization and architecture patterns.

Quick Reference

File size limits:

  • React components: Max 500 lines
  • Hooks: Max 200 lines
  • Extract logic to hooks/sub-components when approaching limits

Component organization:

  • Use sub-components over render functions
  • One component = one concern
  • Compose from smaller pieces
  • 🚨 ALL HOOKS MUST BE UNIT TESTED 🚨

File structure:

  • GraphQL files co-located with components
  • Hooks co-located with components
  • Shared components in components/, not shared/

Sub-components Over Render Functions

Use sub-components (e.g., <Icon />) instead of render functions (e.g., getIcon()).

Benefits:

  • Better readability (step-down rule)
  • Improved performance (no new functions on each render)
  • Easier testing

Props: IDs Over Objects

File Size Limits

React component files must not exceed 500 lines.

Extract logic to hooks, sub-components, or utilities when approaching this limit.

File size guidance:

  • React components: Max 500 lines
  • Hooks: Max 200 lines
  • Utilities: Max 200 lines

File Organization

GraphQL files MUST be co-located with the component/hook that uses them (GraphQL near operation pattern).

Feature Folder Structure

GraphQL File Naming

  • Single query: query.graphql
  • Multiple queries: query-list.graphql, query-detail.graphql
  • Subscriptions: subscription.graphql or subscription-*.graphql
  • Mutations: mutation.graphql or mutation-*.graphql
  • Fragments: fragments.graphql (when shared within feature)

Module Structure

For larger features:

Key principles:

  • GraphQL near operation: Files live next to the component/hook using them
  • No separate graphql/ folder: Don't create module-level graphql/ folders
  • Hooks co-located: Feature-specific hooks live with components
  • Sub-components: Live in same folder as parent

Single Responsibility

One component/hook = one concern.

Composition Over Inheritance

Favor small, composable components over "god" components.

Error Boundaries

Use Error Boundaries to protect pages from crashes. Always log errors to Datadog.

Error Handling in Hooks

Testing

🚨 ALL HOOKS MUST BE UNIT TESTED 🚨

See Unit Testing for comprehensive testing patterns.

Related Documentation

  • Writing Hooks - Custom hooks and useEffect patterns
  • Unit Testing - Testing components and hooks

Reference Files

For more detailed technical guidance, see these reference files:

  • component-sub-components.md
  • component-file-organization.md
  • component-error-boundaries.md
  • arch-composition.md
  • arch-file-size-limits.md
  • arch-single-responsibility.md

Previous

Architecture / Data Fetching

Next

Working on features / Your First Page

On this page

Quick Reference
Sub-components Over Render Functions
Props: IDs Over Objects
File Size Limits
File Organization
Feature Folder Structure
GraphQL File Naming
Module Structure
Single Responsibility
Composition Over Inheritance
Error Boundaries
Error Handling in Hooks
Testing
Related Documentation
Reference Files