Conventions for React Apps

These are conventions I use in React apps so a folder looks like the last one I opened. They are not a style guide for the internet. For JavaScript hygiene I still point people at Clean Code JavaScript.

JavaScript

I write functional, declarative TypeScript. Named functions, small modules, types inferred at the edges.

Names should say what they are. Booleans get a verb: isDisabled, isLoading, hasError, shouldRetry.

I split large components into smaller ones with few props. Composition over a 400-line file with a grab-bag of flags.

Related files live next to the component that owns them. pages/dashboard keeps dashboard-only hooks, types, and pieces. Something becomes shared when a second route needs it, not when I imagine it might.

Folders are lowercase and dashed: components/auth-wizard. Files carry a suffix so I can scan a directory:

  • .config.ts
  • .test.ts
  • .context.tsx
  • .type.ts
  • .service.ts
  • .lib.ts
  • .page.tsx (name matches the route, e.g. dashboard.page.tsx)

Example import: import { NftItem } from './nft-item'

└── nft-item
    ├── index.ts   ( exports )
    ├── nft-item.tsx
    ├── nft-item-header.tsx
    ├── nft-item-footer.tsx
    ├── nft-item-main.tsx
    ├── use-nft-item.ts
    ├── nft-item.type.ts
    ├── nft-item.context.tsx
    └── nft-item.test.tsx

I do not abstract on the first copy. Duplicate once, extract when the third use makes the shape obvious. Kent C. Dodds wrote this up as AHA.

Named exports only. Default exports hide the name from the IDE and from grep.

I let TypeScript infer return types unless the public surface of a package needs an explicit contract.

Functions that take a pile of options use RORO: receive an object, return an object.

// services/account/account.service.ts
export async function getAccounts({ account, limit = 15, offset = 0 }: GetAccountsParams) {
  // Implementation...
  return { accounts: [] }
}
 
// types/services.type.ts
export interface ServiceParams {
  limit?: number
  offset?: number
}
 
// services/account/account.type.ts
export interface GetAccountsParams extends ServiceParams {
  account?: string
}

React

I declare components with function. Hook lint rules are less fussy than with const Component = () =>. Inner helpers inside the file are const so they do not look like components.

Order inside a file: the exported component, then inner components, then types, then copy. Early returns for loading and error. Ternaries in JSX, not &&, so a 0 does not render.

// imports
 
export function MyReactComponent({ myParam }: MyReactComponentParams) {
  const { data, isLoading, error } = useAsyncFn(api.loadData)
 
  const myMethod = () => console.log(myParam)
 
  useEffect(() => {
    console.log('component mounted')
  })
 
  if (isLoading) return <p>loading...</p>
 
  if (error) return <p>error loading data.</p>
 
  return (
    <div className="bg-slate-100 md:flex">
      <p>{content.headline}</p>
      {data ? <h1>{data.title()}</h1> : null}
      {data?.items?.map(Item)}
      <button onClick={myMethod}>{content.button}</button>
    </div>
  )
}
 
function Item({ description }: { description: string }) {
  return <li className="text-blue md:flex">{description}</li>
}
 
export interface MyReactComponentParams {
  myParam: boolean
}
 
const content = {
  headline: 'A new world awaits. Be the first to discover it.',
  button: "Let's go!",
}

Copy in a content object keeps the component readable and is the same shape I need if strings later move to i18n.

Errors

Services and libs throw. The React component (or an async hook) catches and shows a message. Presentational code should not be a nest of try/catch.

For unknown catch values I use the small helpers Kent documented in Get a catch block error message with TypeScript:

export type ErrorWithMessage = {
  message: string
}
 
export function isErrorWithMessage(error: unknown): error is ErrorWithMessage {
  return (
    typeof error === 'object' &&
    error !== null &&
    'message' in error &&
    typeof (error as Record<string, unknown>).message === 'string'
  )
}
 
export function toErrorWithMessage(maybeError: unknown): ErrorWithMessage {
  if (isErrorWithMessage(maybeError)) return maybeError
 
  try {
    return new Error(JSON.stringify(maybeError))
  } catch {
    return new Error(String(maybeError))
  }
}
 
export function getErrorMessage(error: unknown) {
  return toErrorWithMessage(error).message
}

Folders

.
├── index.html
├── package.json
├── postcss.config.ts
├── public
│   ├── favicon.png
│   ├── images
│   │   └── icons
│   ├── index.tsx
│   ├── manifest.webmanifest
│   └── styles
│       ├── global.css
│       └── tailwind.css
├── src
│   ├── app.tsx
│   ├── config
│   │   ├── chain
│   │   ├── client
│   │   └── site.ts
│   ├── icons
│   │   ├── index.ts
│   │   └── lucide.icon.tsx
│   ├── lib
│   │   ├── encoding
│   │   └── error
│   ├── hooks
│   │   ├── use-hook.ts
│   │   └── use-other-hook.ts
│   ├── context
│   │   ├── global.context.ts
│   │   └── other-global.context.ts
│   ├── layouts
│   │   ├── root.layout.ts
│   │   └── sidebar.layout.ts
│   ├── main.tsx
│   ├── pages
│   │   ├── dashboard
│   │   │   ├── index.ts
│   │   │   ├── dashboard.page.tsx
│   │   │   ├── dashboard.type.tsx
│   │   │   ├── dashboard-main.ts
│   │   │   ├── dashboard-footer.ts
│   │   │   ├── dashboard-header.ts
│   │   │   ├── use-dashboard.ts
│   │   │   ├── dashboard.context.ts
│   │   │   └── dashboard.lib.ts
│   │   └── wallet
│   ├── services
│   │   ├── chain
│   │   ├── pinata
│   │   └── sentry
│   ├── shared
│   │   ├── button
│   │   └── modal
│   └── vite-env.d.ts
├── tailwind.config.ts
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

lib is pure functions. No storage, no HTTP, no incidental writes. Input in, value out.

services talks to the world: HTTP, WebSockets, web storage, third-party APIs. Plain functions, not React.

pages is route-owned UI and hooks.

shared is used by more than one page. In a monorepo that often becomes a package.

Layouts are containers. The page passes slots, not a soup of conditionals inside the shell:

import { RootLayout } from 'layouts/root'
 
export function Homepage() {
  return (
    <RootLayout
      aside={
        <>
          <HelpBox />
          <Statistics />
        </>
      }
      heading="Contracts"
    >
      <Contracts />
    </RootLayout>
  )
}

State

Async flags come from useAsync, useAsyncFn, or SWR / TanStack Query: { data, isLoading, error }. The fetch lives in services as vanilla functions. The component only wraps them. Example: useAsyncFn(api.loadData).

If two fields always update together, they are one object. If I can derive a value from props or existing state while rendering, it is not state. I do not copy the same fact into two variables. Nested blobs are harder to update than a flat shape. Persistable state stays JSON-serializable: no class instances, no functions, no Map as the source of truth. Collections in UI state are arrays unless I have a measured reason for a Map.

Zustand and Zod show up when the app needs a small client store or a parser at the boundary. They do not replace these rules.

Related writing