React + TypeScript Style Guide

A clean and consistent guide for writing high-quality React + TypeScript code.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler

🚀 React + TypeScript Style Guide

A structured, scalable, and opinionated style guide for building maintainable React applications with TypeScript. This guide ensures consistency, clarity, and best practices across projects.

📖 Table of Contents

🧠 Philosophy

This style guide is designed to ensure consistency, readability, and maintainability in React + TypeScript projects. By following a structured approach, we aim to reduce cognitive load, improve collaboration, and make codebases easier to scale.

🔹 Core Principles

✅ Summary

By following this guide, teams can write cleaner, more scalable, and easier-to-maintain code. The focus is on consistency, clarity, and minimal cognitive load while following modern React + TypeScript best practices.

📂 Folder Structure

A structured, feature-based folder organization ensures scalability, maintainability, and readability. This structure keeps related files encapsulated while providing clear separation between shared logic and feature-specific implementations.

🔹 General Folder Structure

🔹 Barrel Files & Wildcard Imports

Using barrel files (index.ts) can simplify imports and improve readability, but they should be used with caution. Overuse can lead to unintended re-exports, circular dependencies, and performance issues in certain frameworks like Remix.

When to Use Barrel Files

When to Avoid Barrel Files

Best Practices

❌ Avoid wildcard (*) imports as they increase bundle size, prevent effective tree-shaking, and can introduce unnecessary dependencies.

import * as utils from ‘common/utils’

✅ Prefer named imports for clarity and tree-shaking

import { formatDate, getUserProfile } from ‘common/utils’
app/
├── routes/
├── src/
├── assets/
│   ├── fonts/
│   │   ├── roboto-bold.woff
│   │   ├── roboto-bold.woff2
├── common/
│   ├── components/
│   ├── hooks/
│   │   ├── index.ts
│   │   ├── useFlag.ts
├── config/                      # External service integrations only
│   ├── analytics/
│   │   ├── index.ts
│   │   ├── useLucencyNumber.ts
│   ├── apollo/
│   │   ├── ApolloProvider.tsx
│   │   ├── index.ts
├── constants/                    # Global constants/utils (if used in multiple features)
│   ├── guideUtils.ts             # Example: Used in multiple features
│   ├── index.ts
│   ├── user.ts
├── pages/
│   ├── guide/
│   │   ├── __tests__/
│   │   │   ├── __mocks__/
│   │   │   │   ├── index.ts
│   │   │   │   ├── guideMock.ts
│   │   │   ├── Guide.test.tsx
│   │   │   ├── guideUtils.test.ts
│   │   ├── common/
│   │   │   ├── __tests__/
│   │   │   │   ├── GuideBadge.test.tsx
│   │   │   ├── GuideHero/
│   │   │   │   ├── __tests__/
│   │   │   │   │   ├── GuideHero.test.tsx
│   │   │   │   ├── GuideHero.tsx
│   │   │   │   ├── GuideHeroLoading.tsx
│   │   │   │   ├── index.ts
│   │   │   ├── GuideBadge.tsx
│   │   │   ├── GuideLoading.tsx
│   │   │   ├── index.ts
│   │   ├── hooks/
│   │   │   ├── index.ts
│   │   │   ├── useCreateGuideMutation.ts
│   │   │   ├── useGetGuideQuery.ts
│   │   │   ├── useUpdateGuideMutation.ts
│   │   ├── Guide.tsx
│   │   ├── index.ts               # For cleaner imports
│   │   ├── guideConstants.ts (if needed)
│   │   ├── guideUtils.ts (if needed)
│   │   ├── types.ts (if needed)
│   ├── profile/
│   │   ├── __tests__/
│   │   │   ├── __mocks__/
│   │   │   │   ├── index.ts
│   │   │   │   ├── profileMock.ts
│   │   │   ├── Profile.test.tsx
│   │   │   ├── profileUtils.test.ts
│   │   ├── common/
│   │   │   ├── __tests__/
│   │   │   │   ├── ProfileHero.test.tsx
│   │   │   ├── ProfileHero/
│   │   │   │   ├── ProfileHero.tsx
│   │   │   │   ├── ProfileHeroLoading.tsx
│   │   │   │   ├── index.ts
│   │   │   ├── ProfileLoading.tsx
│   │   │   ├── ProfileSidebar/
│   │   │   │   ├── ProfileSidebar.tsx
│   │   │   │   ├── ProfileSidebarLoading.tsx
│   │   │   │   ├── index.ts
│   │   │   ├── index.ts
│   │   ├── hooks/
│   │   │   ├── index.ts
│   │   │   ├── useCreateProfileMutation.ts
│   │   │   ├── useGetProfileQuery.ts
│   │   ├── Profile.tsx
│   │   ├── index.ts               # For cleaner imports
│   │   ├── profileConstants.ts (if needed)
│   │   ├── profileUtils.ts (if needed)
│   │   ├── types.ts (if needed)

🔹 Why This Works

🎭 Component Structure

A well-structured React component improves readability, maintainability, and consistency. This section defines how components should be structured, including ordering hooks, variables, functions, and the return statement.

🔹 General Rules for Components

🔹 Component Order

Components should follow this order:

✅ Example: Standard Component Structure

export const Profile = () => {
  const navigate = useNavigate()
  const { accountHandle } = useParams()
  const { hasError, isLoading, profileData } = useGetProfileQuery(accountHandle)
  const [searchParams] = useSearchParams()
  const { id, image } = profileData ?? {}

  useEffect(() => {
    // Example: Track analytics
  }, [])

  const getProfileAvatar = () => {}

  const getProfileName = () => {}

  if (isLoading || isEmpty(profileData)) return <ProfileLoading />

  if (hasError) return <ProfileEmpty />

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

🔹 Return Statement Spacing

✅ Example:

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

  if (isLoading || isEmpty(profileData)) return <ProfileLoading />

  if (hasError) return <ProfileEmpty />

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

❌ Avoid cramming return right after logic without spacing.

export const Profile = () => {
  const { hasError, isLoading, profileData } = useGetProfileQuery()
  if (isLoading || isEmpty(profileData)) return <ProfileLoading />
  if (hasError) return <ProfileEmpty />
  return (
    <section>
      <ProfileHero />
      <div>
        <ProfileSidebar />
        <ProfileContent />
      </div>
    </section>
  )
}
export const Profile = () => {
  const { hasError, isLoading, profileData } = useGetProfileQuery()
  return (
    <section>
      <ProfileHero />
      <div>
        <ProfileSidebar />
        <ProfileContent />
      </div>
    </section>
  )
}

🔹 Return Formatting in Functional Components

When returning JSX in functional components, maintain consistent spacing for clarity and readability.

✅ General Rules:

✅ Example: Correct Formatting

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

  if (isLoading) return <ProfileLoading />

  if (hasError) return <ProfileError />

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

❌ Example: Incorrect Formatting

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

  if (isLoading) {
    return <ProfileLoading />
  }

  if (hasError) {
    return <ProfileEmpty />
  }

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

✅ Summary

🔹 Early Returns for Simplicity

To improve readability and reduce indentation, always return early in conditionals rather than nesting them inside larger blocks.

✅ Example: Using Early Return for Cleaner Code

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

  if (isLoading) return <ProfileLoading />

  if (hasError) return <ProfileEmpty />

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

❌ Example: Nested Conditionals (Harder to Read)

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

  if (isLoading) {
    return <ProfileLoading />
  } else {
    if (hasError) {
      return <ProfileEmpty />
    } else {
      return (
        <section>
          <ProfileHero />
          <ProfileContent />
        </section>
      )
    }
  }
}

🔹 JSX Formatting Rules

export const Profile = () => <section>...</section>
export const Profile = () => (
  <section>
    <ProfileHero />
    <ProfileSidebar />
  </section>
)

🔹 Function & Hook Spacing Rules

const navigate = useNavigate()
const { accountHandle } = useParams()
const { hasError, isLoading, profileData } = useGetProfileQuery(accountHandle)
const [searchParams] = useSearchParams()
const { id, image } = profileData ?? {}
const getProfileAvatar = () => {}

const getProfileName = () => {}
const navigate = useNavigate()
const { accountHandle } = useParams()

useEffect(() => {
  // Example: Sync data on mount
}, [])

🔹 Component Naming Conventions

export const ProfileHero = () => <div>Profile Hero</div>
const getProfileName = () => {}

🔹 Loading & Empty State Components

export const Profile = () => (
  <section className='bg-red'>
    <ProfileHero />
    <div>
      <ProfileSidebar />
      <ProfileContent />
      <Button>Click me</Button>
    </div>
  </section>
)
export const ProfileLoading = () => (
  <section className='bg-red'>
    <ProfileHeroLoading />
    <div>
      <ProfileSidebarLoading />
      <ProfileContentLoading />
      <div className='h-12 w-20'>
        <Skeleton variant='rounded' />
      </div>
    </div>
  </section>
)

🔹 When to Split Components?

A component should be split into smaller components if:

🔹 When to Use a common/ Component?

✅ Example (Feature-Specific Component)

pages/profile/common/ProfileHero.tsx

✅ Example (Shared Component)

common/components/ImageWithFallback.tsx

🔹 Why This Works

⚡ Functions & Utilities

This section defines where and how utility functions should be structured to ensure readability and maintainability.

🔹 Utility Function Placement

✅ Example: Utility Function Placement

pages/profile/profileUtils.ts # Feature-specific utilities
constants/userUtils.ts # Shared utilities across features

✅ Example: Exporting Multiple Utilities

const getProfileAvatar = () => {}

const getProfileName = () => {}

export { getProfileAvatar, getProfileName }

🔹 Formatting Rules for Functions

❌ Bad Example (Unnecessary Nesting)

const getUserDetails = user => {
  if (user) {
    return {
      id: user.id,
      name: user.name,
      email: user.email,
    }
  } else {
    return null
  }
}

✅ Good Example (Flat and Readable)

const getUserDetails = user => {
  if (!user) return null

  return {
    id: user.id,
    name: user.name,
    email: user.email,
  }
}

🔹 Return Placement in Functions

Return statements inside functions follow consistent spacing rules for readability.

✅ General Rules

✅ Example: Early return at the start of the function (no blank line)

const getProfileRole = (profileData: ProfileData) => {
  if (!profileData?.id) {
    console.warn('Profile data is missing ID')
    return 'Guest'
  }

  return profileData.role
}

✅ Example: Single-line early return (no extra space needed)

const getProfileRole = (profileData: ProfileData) => {
  if (!profileData?.id) return 'Guest'

  return profileData.role
}

✅ Example: Returning directly in a function with no logic

const getProfileName = (profileData: ProfileData) => `${profileData.firstName} ${profileData.lastName}`

✅ Example: if appears in the middle of the function (needs a blank line before it)

const getProfileName = (profileData: ProfileData) => {
  const { firstName, lastName } = profileData ?? {}

  if (!firstName || !lastName) return 'Guest'

  return `${firstName} ${lastName}`
}

❌ Example: Missing space before if when it’s in the middle of the function

const getProfileName = (profileData: ProfileData) => {
  const { firstName, lastName } = profileData ?? {}
  if (!firstName || !lastName) return 'Guest'

  return `${firstName} ${lastName}`
}

❌ Example: Extra blank line before a return when it’s the only statement

const getProfileName = (profileData: ProfileData) => {

  return `${profileData.firstName} ${profileData.lastName}`
}

❌ Example: Extra blank line before an early return at the start of a function

const getProfileName = (profileData: ProfileData) => {

  if (!firstName || !lastName) return 'Guest'

  return `${firstName} ${lastName}`
}

❌ Example: Single-line early return should stay inline

const getProfileRole = (profileData: ProfileData) => {
  if (!profileData?.id) { return 'Guest' }
}
const getProfileRole = (profileData: ProfileData) => {
  if (!profileData?.id) {
    return 'Guest'
  }
}

🔹 Summary of Return Placement Rules

CaseBlank Line Before Return?
Single return as the only function statement❌ No
Early return at the start of a function❌ No
if appears in the middle of the function✅ Yes
Final return in a function❌ No
Return inside a multi-line if block✅ Yes

🔥 Final Thoughts

Return placement follows the same logic as variables:

By keeping returns structured and predictable, code stays clean, readable, and consistent across the project. 🚀

🔹 Why This Works

📡 GraphQL Queries

A structured approach to handling GraphQL queries and mutations ensures readability, maintainability, and consistency across the application.

🔹 General Rules for GraphQL Queries & Mutations

✅ Example:

src/pages/profile/hooks/useGetProfileQuery.ts # Feature-specific query
src/pages/profile/hooks/useCreateProfileMutation.ts # Feature-specific mutation
src/hooks/useGetPredefinedGuideTagsQuery.ts # Sitewide query (used across features)

✅ Example:

query GetProfileQueryInProfile($id: ID!) { ... }

🔹 Feature-Based Queries vs. Sitewide Queries

To differentiate feature-specific GraphQL queries/mutations from global queries, we use a structured naming convention:

Feature-Based Queries & Mutations

✅ Example:

src/pages/profile/hooks/useGetProfileQuery.ts # Query used only in Profile
src/pages/profile/hooks/useUpdateProfileMutation.ts # Mutation used only in Profile

✅ Query Example:

query GetProfileQueryInProfile($id: ID!) {
  node(id: $id) {
    ... on Profile {
      id
      accountHandle
      displayName
      image
    }
  }
}

Sitewide Queries & Mutations

✅ Example:

src/hooks/useGetPredefinedGuideTagsQuery.ts # Sitewide query

✅ Query Example:

query GetPredefinedGuideTags {
  predefinedGuideTags {
    id
    name
  }
}

🔹 Why This Naming Works

📌 Key Takeaways:

🔹 Example: Query for Fetching Profile Data

import { gql, useQuery } from '@apollo/client'

type UseGetProfileQueryResult = {
  hasError: ApolloError
  isLoading: boolean
  profileData: Extract<
    GetProfileQueryInProfileQuery['node'],
    {
      __typename?: 'Profile'
    }
  >
}

const profileQuery = gql(`
  query GetProfileQueryInProfile($id: ID!) {
    node (id: $id) {
      ... on Profile {
        id
        accountHandle
        displayName
        image
      }
    }
  }
`)

export const useGetProfileQuery = (id: string): UseGetProfileQueryResult => {
  const {
    data,
    error: hasError,
    loading: isLoading,
  } = useQuery(profileQuery, {
    variables: {
      id,
    },
  })

  return {
    hasError,
    isLoading,
    profileData: data?.node,
  }
}

🔹 Why This Works

🔹 Example: Mutation for Updating Profile

import { gql, useMutation } from '@apollo/client'

const updateProfileMutation = gql(`
  mutation UpdateProfileMutationInProfile($updateProfileInput: UpdateProfileInput!) {
    updateProfile(updateProfileInput: $updateProfileInput) {
      id
      displayName
    }
  }
`)

export const useUpdateProfileMutation = () => useMutation(updateProfileMutation)
export const ProfileForm = () => {
  const [updateProfile, updateProfileResult] = useUpdateProfileMutation()

  const onSubmit = async (id: string, displayName: string) => {
    try {
      await updateProfile({
        variables: {
          updateProfileInput: {
            displayName,
            id,
          },
        },
      })
    } catch (error) {
      console.error('Failed to update profile', error)
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <button type='submit'>Update Profile</button>
    </form>
  )
}

🔹 Why This Works

🚩 Feature Flags

Feature flags enable us to conditionally enable or disable features without deploying new code. This approach allows for progressive rollouts, A/B testing, and safe feature releases.

🔹 General Structure

Feature flags are managed using two primary components:

  1. Feature Flags Configuration (featureFlags.ts)

    • This file defines all available feature flags.
    • Flags are stored as a record of boolean values.

  2. Feature Flag Hook (useFlag.ts)

    • A custom hook to read feature flag values.
    • Uses local storage overrides, allowing developers to toggle features locally.

📂 File Structure

src/
├── config/
│   ├── feature-flags/
│   │   ├── featureFlags.ts    # Central feature flag configuration
├── common/
│   ├── hooks/
│   │   ├── useFlag.ts         # Hook to check feature flag status

🔹 Feature Flags Configuration

Feature flags are centrally defined in src/config/feature-flags/featureFlags.ts. This ensures all available flags are explicitly listed.

✅ Example: Defining Feature Flags

// src/config/feature-flags/featureFlags.ts
type FeatureFlagNames = 'profileHeroV2' | 'profileV2'

const featureFlags: Record<FeatureFlagNames, boolean> = {
  profileHeroV2: false,
  profileV2: false,
}

export type { FeatureFlagNames }
export { featureFlags }

🔹 Accessing Feature Flags with useFlag

The useFlag hook retrieves the current state of a feature flag, checking for local storage overrides.

✅ Example: Feature Flag Hook

// src/common/hooks/useFlag.ts
import { useState, useEffect } from 'react'
import type { FeatureFlagNames } from 'src/config/feature-flags/featureFlags'
import { useLocalStorageFlags } from './useLocalStorageFlags'

export const useFlag = (flagKey: FeatureFlagNames | string): boolean => {
  const [isFlagEnabled, setIsFlagEnabled] = useState(false)
  const [localFlags] = useLocalStorageFlags()

  useEffect(() => {
    if (flagKey in localFlags) {
      const { [flagKey]: localStorageFlag } = localFlags
      setIsFlagEnabled(String(localStorageFlag).toLowerCase() === 'true')
    }
  }, [flagKey, localFlags])

  return isFlagEnabled
}

🔹 Using Feature Flags in Components

✅ Example: Conditionally Rendering Components

Feature flags allow conditional rendering of components within a section.

import { useFlag } from 'src/common/hooks/useFlag'
import { ProfileHero } from './ProfileHero'
import { ProfileHeroOld } from './ProfileHeroOld'

export const Profile = () => {
  const isProfileHeroV2Enabled = useFlag('profileHeroV2')

  return (
    <section>
      {isProfileHeroV2Enabled ? <ProfileHero /> : <ProfileHeroOld />}
    </section>
  )
}

🔹 Using Feature Flags for Route-Based Feature Toggles

For larger changes, such as enabling an entirely new Profile redesign, we rename the existing feature folder (profile) to profile-old and introduce a new profile/ folder.

Then, in PageRoutes.tsx, we dynamically choose which version of Profile to render based on the feature flag.

✅ Example: Routing Feature Flag Usage

import { useFlag } from 'src/common/hooks/useFlag'
import { Routes, Route } from 'react-router-dom'
import { Home } from 'src/pages/home'
import { Profile } from 'src/pages/profile'
import { ProfileOld } from 'src/pages/profile-old'

export const PageRoutes = () => {
  const isProfileV2Enabled = useFlag('profileV2')

  return (
    <ScrollToTop>
      <Routes>
        <Route element={<Home />} path='/' />
        <Route
          element={isProfileV2Enabled ? <Profile /> : <ProfileOld />}
          path='/profile/:accountHandle'
        />
      </Routes>
    </ScrollToTop>
  )
}

🔹 Feature Flag Guidelines

✅ Summary

🔠 Types & Interfaces

A consistent approach to defining types and interfaces ensures clarity, maintainability, and flexibility across the codebase.

🔹 General Rules

🔹 Component Props: Use interface

✅ Example: Functional Component Props

interface ProfileHeroProps {
  onClick: () => void
  title: string
}

export const ProfileHero = ({ onClick, title }: ProfileHeroProps) => (
  <div onClick={onClick}>{title}</div>
)

✅ Example: Extending an Interface

Use interface to extend props cleanly, while type uses & for merging multiple types.

import { Button } from '@travelpass/design-system'
import type { GenericAddress } from 'src/__generated__/graphql'

interface ProfileAddressProps extends GenericAddress {
  onClick: VoidFunction
}

export const ProfileAddress = ({
  addressLine1,
  city,
  country,
  onClick,
}: ProfileAddressProps) => (
  <section>
    <h2>{name}</h2>
    <p>{getAddress(addressLine1, city, country)}</p>
    <Button onClick={onClick}>Edit</Button>
  </section>
)

🔹 Utility Types: Use type

Use Pick<> when selecting only specific properties from a type, and Omit<> when removing specific properties.

These help create lightweight, flexible types for better reusability.

✅ Example: Utility Type for Query Results

type UseGetProfileQueryResult = {
  hasError: ApolloError
  isLoading: boolean
  profileData: Extract<
    GetProfileQueryInProfileQuery['node'],
    {
      __typename?: 'Profile'
    }
  >
}

✅ Example: Extracting Only Specific Keys from an Object

type UserKeys = 'id' | 'email'

type UserInfo = Pick<User, UserKeys>

✅ Example: Omitting Unnecessary Fields from an Object

type User = {
  id: string
  email: string
  password: string
}

type PublicUser = Omit<User, 'password'>

✅ Example: Combining Multiple Types

Use & to merge multiple types, providing more flexibility than interface extension.

type Base = {
  createdAt: string
}

type Profile = {
  id: string
  name: string
}

type ProfileWithBase = Profile & Base

🔹 When to Use Extract<> in GraphQL

✅ Example: Extracting the Profile Type from a Query

type UseGetProfileQueryResult = {
  hasError: ApolloError
  isLoading: boolean
  profileData: Extract<
    GetProfileQueryInProfileQuery['node'],
    {
      __typename?: 'Profile'
    }
  >
}

🔹 Avoid Unnecessary interface Usage

❌ Bad Example: Using interface for Utility Types

interface UseGetProfileQueryResult {
  hasError: ApolloError
  isLoading: boolean
  profileData: Profile
}

✅ Good Example: Using type for Flexibility

type UseGetProfileQueryResult = {
  hasError: ApolloError
  isLoading: boolean
  profileData: Profile
}

✅ Summary

📝 Comments & Documentation

A minimalist approach to comments ensures code is clean, readable, and self-explanatory. Instead of excessive commenting, we prioritize descriptive function and variable names. Comments are used only when necessary, such as for complex logic, workarounds, or TODOs.

🔹 General Rules

🔹 Using JSDoc for TODOs

We only use JSDoc (/** @todo */) for tracking future work.

✅ Example: JSDoc TODO for Future Enhancements

/** @todo Update this when the new API version is available */
const getUserPreferences = async (userId: string) => {
  try {
    return await fetch(`/api/preferences/${userId}`)
  } catch (error) {
    console.error(error)
    return null
  }
}

❌ Avoid Unnecessary TODO Comments

This format is not compatible with JSDoc linters.

// @todo Update this when the new API version is available
const getUserPreferences = async (userId: string) => {
  try {
    return await fetch(`/api/preferences/${userId}`)
  } catch (error) {
    console.error(error)
    return null
  }
}

💡 Key Difference:

JSDoc is more structured and aligns with tools that scan TODOs.

🔹 Inline Comments for Workarounds

Use inline // comments for technical workarounds, browser quirks, or unexpected API behavior.

✅ Example: Workaround for Safari Quirk

const scrollToTop = () => {
  window.scrollTo(0, 0)
  // Safari requires a slight delay for smooth scrolling
  setTimeout(() => window.scrollTo(0, 0), 10)
}

✅ Example: Workaround for Safari Quirk with @see

/**
 * Safari requires a slight delay for smooth scrolling.
 * @see https://stackoverflow.com/q/xxxx
 */
const scrollToTop = () => {
  window.scrollTo(0, 0)
  setTimeout(() => window.scrollTo(0, 0), 10)
}

❌ Avoid Redundant Comments

const scrollToTop = () => {
  // Scrolls to the top of the page
  window.scrollTo(0, 0)
}

💡 Key Difference:

🔹 Handling Complex useEffect Hooks

For useEffect, prefer extracting logic into functions instead of writing comments inline.

✅ Example: Extracting Logic Into a Function

useEffect(() => {
  syncUserPreferences()
}, [])

const syncUserPreferences = async () => {
  try {
    /** @todo Remove this workaround when the API provides real-time updates */
    const preferences = await getUserPreferences(user.id)
    applyUserPreferences(preferences)
  } catch (error) {
    console.error(error)
  }
}

❌ Example of an Overloaded useEffect with Comments

useEffect(() => {
  // Fetch user preferences and apply them
  fetch(`/api/preferences/${user.id}`)
    .then(res => res.json())
    .then(preferences => {
      // Apply user preferences
      applyUserPreferences(preferences)
    })
}, [])

💡 Key Takeaway:

🔹 When to Write a Comment vs. Refactor?

Before writing a comment, ask:

✅ Summary

🤝 Contributing

Thank you for considering contributing to this project! We appreciate your help in improving and maintaining this repository.

🔹 How to Contribute

  1. Fork the Repository

    • Click the Fork button on the top right of this repository.
    • This will create a copy under your GitHub account.

  2. Clone Your Fork

    • Run the following command to clone the forked repository:

      git clone https://github.com/YOUR-USERNAME/react-typescript-style-guide.git
cd react-typescript-style-guide

  3. Make your changes in main

    • Open the project in your preferred editor.
    • Make your changes while following the project’s coding guidelines.

  4. Commit your changes

    git add .
git commit -m "Describe your changes"

  5. Push to your fork

    git push origin main

  6. Create a Pull Request

    • Go to the original repository on GitHub.
    • Click Compare & pull request.
    • Add a clear description of your changes.
    • Click Create pull request.

🔹 Contribution Guidelines

✅ Thank you for contributing! We appreciate your support in improving this project. 🚀

📜 License

This project is licensed under the MIT License.

You are free to use, modify, distribute, and share this project with no restrictions, as long as the original license and copyright notice are included.

📄 Full License

The full license text is available in the LICENSE.md file.

📚 References & Inspirations

This style guide follows widely accepted industry standards while maintaining a minimal, structured, and opinionated approach. Below are key resources that align with and support the philosophy, structure, and best practices outlined in this guide.

📌 Key Influences on This Guide

Each of the following references shares core principles with this style guide, such as clarity, maintainability, predictability, and reducing complexity.

ReferenceLinkHow It Relates
Google TypeScript Style GuideGoogle TypeScript Guide✅ Readability & maintainability via consistent naming, structured function ordering, and predictable patterns.
✅ Aligns with Component Order and Separation of Concerns principles.
Airbnb React/JSX Style GuideAirbnb React Guide✅ Focuses on self-contained components, logical function ordering, and clean JSX formatting.
✅ Strongly aligns with Component Structure—especially hooks, variables, and function organization.
Shopify JavaScript & TypeScript GuideShopify JavaScript & TypeScript Guide✅ Encourages feature-based folder structure, aligning with Folder Structure.
✅ Supports encapsulating GraphQL queries within feature folders, similar to our GraphQL Queries section.
TS.dev TypeScript Style GuideTS.dev Guide✅ Emphasizes clarity and minimalism, reinforcing No Unnecessary Abstraction.
✅ Aligns with using interfaces for components and types for utilities/hooks.
TypeScript Deep Dive Style GuideTypeScript Deep Dive✅ Advocates predictable, structured code organization and explicit return types.
✅ Aligns with Types & Interfaces, particularly Extract<>, Pick<>, and Omit<> usage.

💡 Final Thoughts

This style guide follows industry best practices while taking a minimalist approach to ensure scalability, predictability, and maintainability.

By adopting these conventions, you ensure consistency across projects while writing modern, well-structured React + TypeScript code.

🚀 Thank you for following this guide! Your contributions help keep codebases clean, readable, and scalable.