Key takeaway
- A practical React project structure for 2027: feature folders, components, state, testing and code splitting, plus how to start without Create React App.
What is the best React project structure?
There is no single best structure. React is a library for building user interfaces and does not prescribe how files are organised, so the right layout depends on the size of the app and the team. For most teams the sound default is a feature-first layout: keep the components, state logic, tests and styles for one feature together, and put only genuinely shared code (layouts, generic UI components, utilities) in common folders.
This guide shows a practical folder structure, when to group by feature and when by file type, how to split components, and where state, routing, testing and code splitting belong. It also covers how to start a new project in 2026, because Create React App was deprecated on 14 February 2025. For the wider picture, see our React learning path and React.js development services.
How should you start a new React project going into 2027?
According to the React team's guide to starting a new React project, new apps should start with a framework. Your folder structure then follows the framework's conventions, so choose the starting point before you design folders.
| Starting point | When it fits | Status on react.dev |
|---|---|---|
| Next.js (App Router) | Full-stack web apps with server rendering | Recommended framework |
| React Router (v7) with Vite | Routing-led apps, single-page apps and full-stack apps | Recommended framework |
| Expo | Native Android, iOS and web apps | Recommended framework |
| Custom setup with Vite, Parcel or Rsbuild | Unusual constraints, or when you want to own the tooling | Documented in "Build a React app from scratch" |
| Create React App | Existing apps only | Deprecated for new apps; maintenance mode |
What does a typical React folder structure look like?
The layout below is a common starting point, not a rule. Frameworks such as Next.js add their own folders (for example for routes), so adapt the names to your setup.
src/ assets/ images, fonts, global styles layouts/ header, footer, sidebar shared by pages components/ reusable UI: buttons, modals, inputs, loaders pages/ one top-level component per route or view routes/ route definitions and protected or public route wrappers features/ one folder per feature (components, state, tests) services/ API clients and data access config/ environment and application configuration utils/ general-purpose helpers and formatters
| Folder | What belongs there | Keep out |
|---|---|---|
| assets | Images, fonts and global styles | Component logic |
| layouts | Header, footer and sidebar shared across pages | Page-specific content |
| components | Reusable UI building blocks, each with its own test file | Code tied to a single feature |
| pages | Top-level components for each view, composed from smaller components | Reusable widgets |
| routes | Route definitions, including private and public routes and nested routes | Business logic |
| services | API calls and data access | UI code |
| config | Environment-specific settings | Secrets committed to the repository |
| utils | Pure helper functions such as formatters and validators | Anything that needs React state |
Should you group files by feature or by file type?
Both work, and the older React documentation says they are helpful examples rather than strict rules. It describes two common approaches: grouping by features or routes, and grouping by file type. It also suggests limiting nesting to three or four folders, and keeping files that change together close to each other (colocation).
| Approach | When it fits | Trade-off |
|---|---|---|
| By feature | Growing apps and several teams; each team owns a feature | You must decide what a "feature" is, and where shared code lives |
| By file type | Small apps and prototypes | One change touches many folders as the app grows |
| Hybrid | Most production apps | Needs a written rule for what counts as shared |
For state management, the Redux style guide says that most applications should use a feature folder approach, with the Redux logic for each feature in a single slice file, and notes that older codebases often used separate folders for actions and reducers. If you inherited a services folder split into actions, reducers and constants, a feature-based move is worth planning.
How do you decide what becomes a component?
The React documentation's Thinking in React gives a simple test: a component should ideally be concerned with one thing, and if it grows it should be split into smaller components. It also suggests that a well-structured data model often maps naturally to the component structure of the UI. Draw boxes around each part of a mockup, name them, and nest them into a hierarchy before writing code.
Where do state, routing and styles belong?
-
Local state stays in the component that owns it. Lift it up only when two components need it.
-
Shared state can use the Context API for values such as theme or the signed-in user, or Redux Toolkit when many features share complex state. Keep that logic inside the feature that owns it.
-
Routing lives in the framework's router or a dedicated routes folder, so protected and public routes are defined in one place.
-
Styles sit next to the component they style (CSS Modules or a CSS-in-JS library), with only global styles in assets, so changes do not leak across the app.
-
Naming: choose one convention for components, variables and files, and enforce it with ESLint and Prettier rather than review comments.
How do you keep a React project fast and tested?
Structure supports two habits that matter at scale. First, split code by route or feature so users download only what they need. According to the React reference, lazy defers loading a component's code until it is first rendered, and you wrap it in a Suspense boundary to show a fallback while it loads. It relies on dynamic import(), which may need support from your bundler or framework. Our guide to optimising React application performance goes further, and React Server Components change what runs on the client.
Second, keep a test file beside each reusable component. Our guides on test-driven development with React and Jest and testing React components cover the methods. Where teams also use AI agents in development or testing, a quality layer such as AgentQA, which describes itself as catching hallucinations, errors and data quality issues before users do, can sit alongside your normal unit and integration tests.
Which mistakes make React projects hard to maintain?
| Mistake | Why it hurts | Better habit |
|---|---|---|
| Over-nested folders | Long relative imports are hard to write and maintain | Limit nesting to three or four levels |
| No reusable components | Repeated code is slower to change | Extract a component once it is used in a second place |
| Everything in one global store | Features become coupled | Keep state in the feature that owns it |
| No linting or type checking | Common errors reach production | Use ESLint and TypeScript from day one |
| No error handling | Failures are hard to diagnose | Add error boundaries and logging early |
| Loading everything up front | Slow first load | Split code by route or feature |
What is a sensible adoption sequence?
-
Pick the framework or build tool first, then follow its folder conventions.
-
Start with a small structure (components, pages, utils) and add folders only when a real need appears.
-
Move to feature folders once more than one team or a dozen screens are involved.
-
Write the rules down: what counts as shared, how files are named, where tests live.
-
Enforce the rules with linting and review checklists, and revisit them as the app grows.
Why does project structure matter to enterprise teams?
In our view, a predictable structure lowers onboarding time, makes ownership clear (one team per feature folder) and keeps changes reviewable, including changes proposed by AI coding tools. The structure should also make it obvious where business rules and data access live, so they can be audited. As more of the user interface becomes agent-driven, those decisions need governed context behind them. Our guide to agentic workflows covers the patterns, and ElixirData describes its Context OS as gathering the right business information for an AI agent at decision time, checking policy and authority before the agent can act, and keeping a record of each decision.
To map one decision your agents should make in a React-based product, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.
What should you plan for in 2027?
Your build tooling will move during 2027, so keep the project structure independent of any one Node.js version.
- Node.js 27 arrives in April 2027. The Node.js release schedule announcement says Node.js 27.0.0 is due in April 2027 and moves to long term support in October 2027, with one major release a year from then on.
- Node.js 26 changes phase in October 2027. The same page lists Node.js 26 entering maintenance in October 2027, so plan upgrades for build servers and framework toolchains. It notes the schedule is not final.
- Keep structure rules separate from tooling. Feature folders, written naming rules and tests beside components survive a framework or runtime upgrade.
Frequently asked questions
Is Create React App still the way to start a React project?
No. The React team deprecated it for new apps on 14 February 2025 and recommends starting with a framework such as Next.js, React Router or Expo, or a build tool such as Vite, Parcel or Rsbuild for custom setups. Existing apps continue to work in maintenance mode.
Should I organise React files by feature or by type?
Small apps can group by type. As an app grows, grouping by feature keeps related files together, and the Redux style guide recommends feature folders for most applications. Many teams use a hybrid with shared code in common folders.
How deep should React folders nest?
The older React documentation suggests limiting yourself to a maximum of three or four nested folders, because deep hierarchies make relative imports harder to write and maintain.
Where should tests live in a React project?
Keep each test file next to the component or feature it covers, so tests move with the code. Reusable components in particular should each have a test file.
How does code splitting fit the folder structure?
Split at route or feature boundaries. React's lazy function loads a component's code when it is first rendered, and a Suspense boundary shows a fallback meanwhile.
Actionable Next Steps for React Development
Talk to our experts about implementing an optimized Reactjs project structure. Learn how industries and departments use Agentic Workflows and Decision Intelligence to become decision-centric. Leverage React best practices to automate and streamline IT support and operations, enhancing efficiency and responsiveness.
Ready to put AI agents to work? See an ElixirClaw demo: the agentic OS to build, orchestrate and govern AI agents across your enterprise systems.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE