How to Scale a React App Without Losing Your Mind

You run one command, you get a main.tsx, you put everything in it, and it works. No architecture meetings. No RFC. No one asking you where the domain layer is. Just you, a component, and vibes.

The part where it quietly goes downhill

The frustrating part is that nobody did anything wrong. Every individual decision was reasonable. The structure just does not scale, because it is organized by what a file is instead of what a file is for.

Okay, so what is the fix?

Scaling is five problems wearing a trench coat

Under all five sits the least glamorous thing in software: naming.

Good names mean you do not need a comment explaining what a file does. The name is the comment. Unlike the comment, it cannot quietly go out of date.

Names that do the explaining for you

Here is a small slice of a teams feature. Read the file names and try to guess what the UI looks like:

The composition tree is visible in the file tree. teams-list renders teams-list-item, which renders teams-list-item-menu. The names are prefixed, so they sort together, and so Cmd+P becomes a genuinely good navigation tool. Type teams-list and everything about that screen is in front of you.

Use cases first, file types second

teams
├─ components
├─ hooks
├─ schemas
├─ types
├─ queries
├─ mutations
└─ utils

The second one reads like a product spec, because it is one. Those are the things a user can do with a team.

Here is the full picture for a mature teams feature:

Now imagine a ticket lands: the create-team dialog should validate names against a two-character minimum.

components/create-team-form.tsx
schemas/create-team.schema.ts
hooks/use-create-team.ts
api/mutations.ts
types/team.types.ts

In the new structure, you open create/ and everything is right there. That locality is the biggest thing vertical slices buy you.

Let’s talk data fetching, because that is where it always breaks

The pattern that has aged best for me: keep query and mutation config in plain exported files, not hooks.

export const teamDetailsQueryOptions = (teamId: string) =>
  queryOptions({
    queryKey: teamQueryKeys.detail(teamId),
    queryFn: () => getTeam({ teamId }),
    staleTime: 30_000,
  });

const { data: team } = useSuspenseQuery(
  teamDetailsQueryOptions(teamId),
);

export const createTeamMutationOptions = () =>
  mutationOptions({
    mutationFn: createTeam,
    onSuccess: async (_, __, ___, context) => {
      await context.client.invalidateQueries({
        queryKey: teamQueryKeys.lists(),
      });
    },
  });

The hook tax

useTeams()
useTeam()
useCreateTeam()
useUpdateTeam()
useDeleteTeam()

export const useTeam = (id: string) =>
  useQuery(teamQueryOptions(id));

use-team-selection.ts       // multi-select across a list
use-team-permissions.ts     // role logic, derived flags
use-team-dnd.ts             // drag-and-drop wiring
use-team-member-search.ts   // debounce + filter + highlight
use-teams-list-filters.ts   // URL state sync + defaults

Schemas: one per intent, not one per model

There is a strong temptation to write a single team-schema.ts that describes the team forever, in all contexts. Do not. Reading a team and creating a team are different contracts with different rules.

export const teamSchema = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string().nullable(),
  memberCount: z.number(),
  createdAt: z.string(),
});

Force these into one schema and you end up with a pile of .optional() and .partial() and a type that is true nowhere in particular.

Do not create types.ts just because TypeScript exists

type TeamsListItemProps = {
  team: Team;
};

export function TeamsListItem({ team }: TeamsListItemProps) {
  // ...
}

Promote it to team-types.ts only when multiple files in the feature genuinely share it. A types file that exists “for organization” is a file you now have to keep in sync.

utils.ts is where code goes to be forgotten

utils.ts
helpers.ts
lib.ts
common.ts

The fix is embarrassingly simple: name the file after what it does.

team-mappers.ts
team-permissions.ts
team-sort.ts
team-filters.ts
team-formatters.ts
team-member-rules.ts
team-query-params.ts

// tells you nothing
import { canManageTeam } from '../utils';

// tells you everything
import { canManageTeam } from '../shared/team-permissions';

Where does state actually go?

type TeamSelectionState = {
  selectedTeamIds: Set<string>;
  select: (id: string) => void;
  deselect: (id: string) => void;
  clear: () => void;
};

Query keys deserve one file and a little respect

export const teamQueryKeys = {
  all: ['teams'] as const,

  lists: () => [...teamQueryKeys.all, 'list'] as const,
  list: (filters: TeamsListFilters) =>
    [...teamQueryKeys.lists(), filters] as const,

  details: () => [...teamQueryKeys.all, 'detail'] as const,
  detail: (teamId: string) =>
    [...teamQueryKeys.details(), teamId] as const,

  members: (teamId: string) =>
    [...teamQueryKeys.detail(teamId), 'members'] as const,
};

Now invalidation says what it means. Creating a team invalidates teamQueryKeys.lists(). Adding a member invalidates teamQueryKeys.members(teamId) and leaves everything else alone. The hierarchy is real, typed, and lives in one place.

The shared/ folder problem

Three features need the same card component. Your hand moves toward shared/ on instinct. That is fine once or twice. By the fortieth time, shared/ is a 200-file junk drawer: the flat components/ folder you escaped, wearing a fake moustache.

Before you put it in shared/, ask one question: is there a parent feature hiding here?

features
├─ mammals/
├─ cat/
├─ dog/
└─ shared/
   └─ mammal-detail-card.tsx

Features can nest. Nesting gives you a natural scope for shared code, so root shared/ stays reserved for things that are genuinely app-wide: the design system, auth, and the API client.

But I already have a mess

Wrapping up

• Organize by use case, not by file type.
• Let file names carry the explanation. Long and boring beats short and mysterious.
• Keep query and mutation config as plain objects; make hooks earn their existence.
• Use one schema per intent, not one schema per model.
• Never create a folder named utils.
• Walk down the state ladder: URL → Query → React → form library → store.
• Nest features instead of feeding a giant shared/.
• Know when to stop. Abstraction is a tool, not a personality.