Skip to main content
XenonStack

Enterprise Digital Platform

XenonStack Insights React Project Structure: Folders and Best Practices

and | Published | Updated

React Project Structure: Folders and Best Practices
12:22
React project structure: folders, features and a 2026 starting point, shown as a four-layer stack from framework choice to a maintainable app

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 pointWhen it fitsStatus on react.dev
Next.js (App Router)Full-stack web apps with server renderingRecommended framework
React Router (v7) with ViteRouting-led apps, single-page apps and full-stack appsRecommended framework
ExpoNative Android, iOS and web appsRecommended framework
Custom setup with Vite, Parcel or RsbuildUnusual constraints, or when you want to own the toolingDocumented in "Build a React app from scratch"
Create React AppExisting apps onlyDeprecated 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.

Two-column diagram: left lists features, components, pages and routes, services and utils folders; right lists what each holds, ending in related files changing together.
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
FolderWhat belongs thereKeep out
assetsImages, fonts and global stylesComponent logic
layoutsHeader, footer and sidebar shared across pagesPage-specific content
componentsReusable UI building blocks, each with its own test fileCode tied to a single feature
pagesTop-level components for each view, composed from smaller componentsReusable widgets
routesRoute definitions, including private and public routes and nested routesBusiness logic
servicesAPI calls and data accessUI code
configEnvironment-specific settingsSecrets committed to the repository
utilsPure helper functions such as formatters and validatorsAnything 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).

ApproachWhen it fitsTrade-off
By featureGrowing apps and several teams; each team owns a featureYou must decide what a "feature" is, and where shared code lives
By file typeSmall apps and prototypesOne change touches many folders as the app grows
HybridMost production appsNeeds 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?

MistakeWhy it hurtsBetter habit
Over-nested foldersLong relative imports are hard to write and maintainLimit nesting to three or four levels
No reusable componentsRepeated code is slower to changeExtract a component once it is used in a second place
Everything in one global storeFeatures become coupledKeep state in the feature that owns it
No linting or type checkingCommon errors reach productionUse ESLint and TypeScript from day one
No error handlingFailures are hard to diagnoseAdd error boundaries and logging early
Loading everything up frontSlow first loadSplit code by route or feature

What is a sensible adoption sequence?

  1. Pick the framework or build tool first, then follow its folder conventions.

  2. Start with a small structure (components, pages, utils) and add folders only when a real need appears.

  3. Move to feature folders once more than one team or a dozen screens are involved.

  4. Write the rules down: what counts as shared, how files are named, where tests live.

  5. 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.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue