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.

✅ 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

A feature is a self-contained module that represents:

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

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.

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

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

Additional Resources:

• TypeScript Handbook: Types vs. Interfaces

Additional Resources:

• Feature Flags Best Practices

✅ 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

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.