How I Structure a Large React Application

Many React applications begin with a structure like this:

src/
|-- components/
|-- hooks/
|-- services/
|-- types/
|-- utils/
`-- pages/

It feels organized because every file has a technical category. The problem is that these categories say nothing about product ownership.

An order-history table, a checkout dialog, and the main navigation are all components. A currency formatter, a permission check, and a checkout calculation can all be called utilities. A data-fetching hook and a keyboard shortcut hook are both hooks, even though they belong to completely different parts of the product.

As the application grows, these folders develop predictable failure modes:

• Developers must search across several global directories to understand one feature.
• Similar names accumulate because the folder no longer provides business context.
• Private implementation details become convenient imports for unrelated features.
• Changes that should be local require edits in components, hooks, services, types, and utils.
• Nobody knows what is genuinely shared and what merely ended up in a shared location.
• Circular dependencies appear because there is no declared direction of travel.

The problem is not the words components, hooks, or utils. I still use those folders inside a bounded module. The problem is making technical type the highest-level organizing principle.

At the application level, I organize by responsibility and reason to change.

A feature is a behavior a user or another system can perform: cancel an order, invite a team member, update a payment method, export a report. I prefer capability names over vague areas such as dashboard or common.

A feature module may own:

• The React components used to perform that capability.
• Feature-specific hooks and interaction state.
• Validation and form mapping.
• API operations used only by the feature.
• Coordination between domain rules and infrastructure.
• Tests that protect the feature's behavior.

This keeps the files that change together close together. A developer working on order cancellation should not need to visit six global folders to trace one interaction.

Feature-based organization does not mean putting everything related to orders in one enormous orders folder. A domain is a business concept. A feature is an operation involving that concept. That distinction stops a large domain module from becoming the next dumping ground.

The route or application layer composes features. One feature should not reach into another feature's internal files to borrow a hook or component. If two features need the same business rule, that rule probably belongs to a domain module. If they need the same technical primitive, it probably belongs in shared.

I separate transport mechanics from product operations.

The shared API layer may own concerns such as the base URL, authentication headers, request cancellation, error normalization, tracing headers, and JSON parsing. It should not know how to cancel an order or invite a member.

The relevant feature or domain adapter owns endpoint paths, request and response DTOs, and the mapping between transport data and application types.

import { httpClient } from "@/shared/api";

type CancelOrderResponseDto = {
  order_id: string;
  status: "cancelled";
  cancelled_at: string;
};

export async function cancelOrder(orderId: string) {
  const response = await httpClient.post<CancelOrderResponseDto>(
    `/orders/${orderId}/cancellation`,
  );

  return {
    orderId: response.order_id,
    status: response.status,
    cancelledAt: new Date(response.cancelled_at),
  };
}

This boundary prevents wire formats from leaking through components and domain rules. If the backend renames a field or returns a new representation, the change is absorbed where the external contract enters the module.

I avoid one global api.ts or services.ts containing every endpoint. Those files centralize unrelated volatility. They look convenient until every team must edit the same module and every consumer can import every operation.

The dependency model is intentionally simple:

app  ----> features ----> domains
 |           |              |
 +-----------+--------------> shared

• App may compose features, domains, and shared primitives.
• Features may depend on domain modules and shared infrastructure.
• Domains may depend on small, stable shared primitives, but not on features or app.
• Shared must not depend on product features or domains.
• A feature must not import another feature's private implementation.

When two features need to coordinate, I compose them in the application layer or extract the stable business behavior they share. I do not solve the problem with a deep relative import.

These rules should be enforceable. Path aliases improve readability, but they do not create boundaries. In a larger team I add restricted-import lint rules, module-boundary tooling, or package exports so an invalid import fails before code review. In a monorepo, the same rules can be expressed as package dependencies.

There are legitimate exceptions. A boundary rule should make unusual coupling visible, not force developers into elaborate workarounds. When I allow an exception, I record why the dependency exists, who owns it, and what would let us remove it later.

I organize tests by ownership, not by test-library vocabulary.

src/
|-- domains/orders/tests/
|   `-- can-cancel-order.test.ts
|-- features/cancel-order/tests/
|   |-- cancel-order-contract.test.ts
|   `-- cancel-order-dialog.test.tsx
`-- shared/testing/
    |-- render-application.tsx
    |-- factories/
    `-- server/

e2e/
`-- cancel-order.spec.ts

Pure domain tests live with the domain. Feature behavior and contract tests live with the feature. Shared testing contains infrastructure used by many modules: render wrappers, factories, deterministic builders, and network handlers. It must not become a second utils folder filled with business-specific fixtures.

End-to-end tests live at the repository level because they exercise deployed user journeys across module boundaries. Their folder reflects the scope of the test, not a preference for a particular runner.

A top-level tree divided into unit, integration, and component tests usually recreates the same navigation problem as components, hooks, and utils. Those labels describe how a test runs. They do not say who owns the behavior when it fails.

I would not stop delivery to reorganize an existing application into this tree. Large restructures create churn without proving that the new boundaries are better.

Instead, I choose one meaningful vertical slice. I move its UI, interaction logic, API adapter, and domain rules behind one feature API. I fix the dependency direction around that slice, then use the next feature to test whether the pattern still holds.

The structure earns its place when routine changes become more local, private code stays private, and developers can explain why a dependency is allowed. If a boundary repeatedly fights the product, I change the boundary. Consistency is valuable, but protecting the wrong abstraction is not.