React + TypeScript Feature-First Style Guide

A feature-first approach to building scalable, maintainable, and predictable React applications with TypeScript. Designed for clarity, consistency, and efficiency, this guide minimizes cognitive load and enforces best practices.

Core Principles

• Feature-First Development - Features are self-contained and organized around routes.
• Minimal Cognitive Load - Engineers should immediately know where code belongs.
• Predictability & Consistency - Every feature follows the same structure.
• No Unnecessary Abstractions - Complexity is only introduced when necessary.
• Automation Over Convention - Enforceable via ESLint/Prettier instead of manual rules.

Additional Resources:

• Google TypeScript Style Guide
• Airbnb React Style Guide
• My React TypeScript Style Guide
• Vercel React Best Practices

Feature-First Folder Structure

What is a Feature?

A feature is a self-contained module that represents:

• A route (/guides/:guideId)
• A significant UI section
• Reusable business logic specific to a domain

Feature Structure Example

pages/guides/search  → Feature (route: `/guides/search`)
  GuideSearch.tsx  → Main component

pages/guides/:guideId  → Feature (route: `/guides/:guideId`)
  Guide.tsx  → Main component
  hooks/useGetGuideQuery.ts  → Query for getting details
  hooks/useGuideMetricShare.ts  → Handles copy-to-clipboard/sharing
  components/GuideHero.tsx  → Feature-scoped component

pages/profile/:accountHandle  → Feature (route: `/profile/:accountHandle`)
  Profile.tsx → Main component

pages/profile/:accountHandle/guides  → Feature (route: `/profile/:accountHandle/guides`)
  ProfileGuides.tsx → Main component

• Flat structure: No deep nesting inside features.
• Feature-scoped: Hooks and components belong inside the feature they support.
• No common/ folder - Instead, use src/hooks/ for sitewide hooks and src/components/ for reusable components.

Component Structure

Ordering Inside a Component:

1. Hooks (useState, useEffect, etc.)
2. Local Variables (constants, derived values)
3. useEffect Hooks (side effects, lifecycle logic)
4. Event Handlers & Functions
5. Return Statement (JSX)

Example Component:

export const Profile = () => {
  const { hasError, isLoading, profileData } = useGetProfileQuery()

  if (isLoading) return <ProfileLoading />

  if (hasError) return <ProfileEmpty />

  return (
    <section>
      <ProfileHero />
      <ProfileContent />
    </section>
  )
}

Naming Conventions

GraphQL Queries & Mutations

Correct Naming Examples:

query GetGuide($id: ID!) { ... }             # Fetches full guide details
query GetGuideEvents($guideId: ID!) { ... }  # Fetches related guide events
query GetGuideImages($guideId: ID!) { ... }  # Fetches guide images

Additional Resources:

• GraphQL Best Practices

Types & Interfaces

Additional Resources:

• TypeScript Handbook: Types vs. Interfaces

Feature Flags

Additional Resources:

• Feature Flags Best Practices

Comments & Documentation

• Code should be self-explanatory; avoid unnecessary comments.
• Use JSDoc @todo for tracking future work.
• Only document “why”, not “what” the code does.

Example:

/** @todo Remove this workaround when the new API version is available */
const getUserPreferences = async (userId: string) => {
  return await fetch(`/api/preferences/${userId}`)
}

Additional Resources:

• Clean Code Principles

Final Thoughts

This cheat sheet ensures clarity, predictability, and minimal cognitive load.

• Keep rules minimal & enforceable.
• Follow automation-first principles.
• Structure code in a way that scales naturally.

This is your definitive React + TypeScript Feature-First Style Guide, designed to reduce thinking, improve efficiency, and create scalable applications effortlessly.