Building Blocks: A Scalable React Architecture

· 454 words · 3 minute read

React SPA offers the flexibility to create stunning web applications with superb interfaces and user experiences. But, it falls short in providing guidelines on app organization. Let’s analyze a simple yet robust and scalable architecture solution for your React applications.

Whether you’re using a basic template or Create React App to setup your project, choosing the app’s structure is a big deal. This decision is key and can really shape the rest of your work on the project.

A flexible architecture

├── routes
│   ├── admin
│   │   ├── AdminBoard.tsx
│   │   └── index.tsx
│   └── dashboards
│       ├── Dashboards.tsx
│       ├── index.tsx
│       ├── trends
│       │   ├── PastTrends.tsx
│       │   ├── FutureTrends.tsx
│       │   ├── index.tsx
│       │   └── hooks
│       │       └── useTrendCalculator.ts
│       └── forecasts
│           └── index.tsx
├── lib
│   └── dates.ts
└── shared
    ├── hooks
    │   └── useWindow.ts
    └── components
        ├── button
        │   └── index.tsx
        ├── datepicker
        │   ├── calendar.tsx
        │   └── index.tsx
        └── barchart
            └── index.tsx

My focus here is on the architecture of a React single-page app. I’ll leave out details like TypeScript configuration files, routing files, and entry points. These files usually sit at the root level and that’s generally good enough for most apps.


I aim to design an architecture that mirrors the business we’re modeling. One effective way to do this is by organizing files based on routes. In the routes folder, we create sub-folders corresponding to the pages we’re displaying, such as admin and dashboards.

Inside these, there is an index.tsxfile, typically a smart component coordinating API calls and data handling. The rest of the route’s components are mainly UI components.

A key point to highlight is the use of extra folders like hooks or lib, which keeps related code together. If code needs to be reused, it’s relocated to the src/shared folder where shared components and hooks are stored.

Another crucial detail is that nested routes correspond to nested folders. This allows the folder structure to directly reflect the navigation path. Inside these, the same structure is replicated.


Here you can keep all the logic you reuse across your application. Business logic, components, hooks, etc.


You’ll often need a ‘utils’ or ’lib’ folder in a React application. This is the perfect spot for pure functions handling various tasks like data processing or transformations. It’s a neat way to keep this kind of code organized.

There are numerous other aspects to consider when designing a project architecture: state management, testing, optimization, etc. These factors could potentially impact how you structure the application. Always remain flexible and adapt the architecture to fit the project’s requirements.

If this organization method doesn’t feel comfortable to you, consider exploring more feature/domain-driven architectures.