Most React codebases start simple. A handful of components, a couple of pages, some shared utilities. Six months later there are 200 components, five developers, and nobody is quite sure where new features belong. What started as a small project now takes twice as long to extend because the structure that made sense at the beginning does not accommodate the complexity that followed.
The good news is that a small amount of structural discipline upfront prevents most of this. The choices that matter most are not about which state management library to pick or whether to use class components or hooks. They are about where you draw boundaries between different kinds of code.
Why Application Structure Is a Maintenance Decision
Every file in a codebase has an implicit claim about what it does and what it depends on. When a component file contains a database fetch, a formatting function, and a button click handler, all of that is mixed together without clear boundaries. Extending it requires reading and understanding everything in the file. Testing it requires mocking everything it touches.
Structure is how you make those implicit claims explicit. A component that only handles UI rendering is easy to understand because its scope is narrow. A service function that only handles API calls is easy to test because its dependencies are limited and predictable. Good structure is not about following a pattern for its own sake; it is about making the codebase tell the truth about what each file is responsible for.
This becomes especially important when the team grows. A developer joining a well-structured codebase can find where to make a change without reading everything. In a poorly structured one, every change requires a full context audit.
Feature-Based Folder Organization
The most durable folder structure for React applications organizes code by feature, not by type. Type-based organization looks like this:
src/
components/
hooks/
services/
utils/
pages/Feature-based organization looks like this:
src/
features/
auth/
components/
hooks/
services/
dashboard/
components/
hooks/
api.ts
shared/
components/
utils/The type-based structure seems intuitive at first. All hooks are together. All components are together. The problem is that as the project grows, components/ becomes hundreds of files with no clear relationship to each other. Changing the authentication flow requires touching files in components/, hooks/, and services/, and finding which ones requires knowing the naming conventions rather than the feature boundaries.
Feature-based structure means that everything related to authentication is in features/auth/. Adding a new auth feature requires editing files in one place. Removing the auth feature means deleting one folder. The structure supports the natural unit of work rather than fighting it.
Photo by Walls.io on Pexels
Separating UI Components from Business Logic
The single most valuable structural decision in a React codebase is keeping UI components focused on UI and pushing business logic out of component files. This sounds simple and is routinely ignored.
A UI component answers one question: given some props, what should render? It should not be making API calls, transforming data structures, or implementing business rules. When it does those things, it becomes untestable in isolation and impossible to reuse.
The separation has a practical pattern. Write components that receive data and callbacks as props. Write hooks that fetch data, transform it, and expose callbacks. Write service functions that handle API requests. The component composes from what the hook provides; the hook composes from what the services provide.
// Component: only UI concerns
function UserProfile({ user, onEdit }: UserProfileProps) {
return (
<div>
<h1>{user.displayName}</h1>
<p>{user.email}</p>
<button onClick={onEdit}>Edit</button>
</div>
);
}
// Hook: data fetching and transformation
function useUserProfile(userId: string) {
const [user, setUser] = useState<User | null>(null);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
fetchUser(userId).then(setUser).finally(() => setIsLoading(false));
}, [userId]);
return { user, isLoading };
}This structure makes the component testable with any user object you pass it. The hook is testable by mocking the fetch function. Neither depends on the other's implementation details.
React's official documentation covers custom hook patterns in detail, including when to extract logic and how to compose hooks.
Managing State at the Right Level
State management is where many React codebases develop unintended complexity. Not because the state management library is too complicated, but because state is put at the wrong level of the component tree.
The rule that prevents most state-related refactoring work is: state should live as close to the components that use it as possible. This means:
Local state (a form field, a dropdown toggle) lives in the component that owns it. It does not need to be global. It does not need to be in a Context.
Shared state between sibling components lives in their closest common ancestor. It stays there until there is a concrete reason to move it higher.
Application-wide state (authentication, user preferences, shopping cart) lives in a global store or Context. But the threshold for making state global should be high. Most state that ends up global was promoted there before it was necessary.
// Before: premature global state
const { user, theme, cart, filterState, selectedTab } = useGlobalStore();
// After: state at the right level
// Global: user, theme, cart (genuinely shared)
// Component: filterState, selectedTab (only used locally)Keeping state local by default makes components easier to understand because their behavior is self-contained. When you do need global state, it is genuinely global rather than a dumping ground for everything that needed to be accessed in more than one place.
"The teams that have the hardest time refactoring React applications are usually the ones who put all business logic in component files early on. Component boundaries should describe UI composition, not business rules." - Dennis Traina, founder of 137Foundry
Handling Routing and Code Splitting
Routing structure mirrors feature structure in a well-organized codebase. Each top-level route corresponds to a feature, and route files are thin wrappers that compose feature components.
React Router supports lazy loading with React.lazy() and Suspense, which pairs naturally with a feature-based structure. Each feature folder's entry point can be lazy-loaded, so the initial bundle only includes what is needed for the landing page.
import { lazy, Suspense } from 'react';
import { Routes, Route } from 'react-router-dom';
const Dashboard = lazy(() => import('./features/dashboard'));
const Settings = lazy(() => import('./features/settings'));
function App() {
return (
<Suspense fallback={<LoadingSpinner />}>
<Routes>
<Route path="/dashboard" element={<Dashboard />} />
<Route path="/settings" element={<Settings />} />
</Routes>
</Suspense>
);
}This also enforces the feature boundary: each feature is a loadable unit. Code that is not in the feature folder does not get included in the feature's bundle.
Photo by Brett Sayles on Pexels
Using TypeScript to Enforce Boundaries
TypeScript is valuable for React applications primarily because it makes structural boundaries enforceable. Without TypeScript, a component can receive any props, a function can return any shape, and a hook can depend on any global. Types make the contracts visible.
The most useful TypeScript practice for maintainability is explicit return types on hooks and service functions. This forces you to define the interface upfront and makes changes to the underlying implementation explicit. If a hook's return type changes, TypeScript tells you every place in the codebase that breaks.
TypeScript integrates directly with Vite and Create React App, so the setup overhead is minimal for new projects. For existing projects, gradual adoption by adding // @ts-check to JavaScript files and incrementally adding type annotations is more realistic than a full rewrite.
Enforcing Conventions with Linting
Structure decisions only work if the team follows them consistently. ESLint rules let you automate the enforcement of conventions that would otherwise require code review attention on every PR.
ESLint with the React and TypeScript plugins covers the most common violations: missing dependency arrays in useEffect, props that should be destructured, and hook call conventions. For enforcing import boundaries between features, eslint-plugin-boundaries allows you to define which features are allowed to import from which, making cross-feature dependencies explicit and flaggable.
The setup is a one-time investment that pays back on every subsequent PR review. Reviewers spend time on logic and design decisions rather than convention enforcement.
Signs Your Structure Is Working
You will know your structure is working when these things are true: a developer who is new to the codebase can find the file responsible for a feature without asking for a tour; adding a new feature requires creating files in one new folder rather than modifying files across many existing ones; a unit test for a component does not require mocking a dozen dependencies; and removing a deprecated feature is a folder deletion rather than a search-and-replace operation.
These are achievable goals for any React codebase. They do not require a specific library or a particular folder naming scheme. They require consistent application of the principles of narrow responsibility, feature-based co-location, and state at the right level.
For teams building or refactoring production React applications, https://137foundry.com offers web development services ranging from architecture review to full application builds.
Photo by panumas nikhomkhai on Pexels
Summary
React application structure is a set of decisions about where code lives and what it is responsible for. Feature-based folder organization keeps related code co-located. Separating UI from business logic makes components testable and reusable. State should live as close to where it is used as possible. TypeScript makes structural contracts enforceable. ESLint automates convention enforcement.
None of these require a large refactor to start applying. Pick the practice most relevant to the current pain point, apply it to new code, and refactor existing code incrementally. The 137Foundry services hub includes web development advisory for teams working through these kinds of architectural decisions.
