Folder structure best practices in React - Deep Dive

Overview - Folder structure best practices

What is it?

Folder structure best practices in React are guidelines on how to organize files and folders in a React project. This helps keep the code clean, easy to find, and simple to maintain. It involves grouping related files like components, styles, and assets logically. Good structure makes teamwork smoother and helps the project grow without chaos.

Why it matters

Without a clear folder structure, projects become messy and hard to understand, especially as they grow. Developers waste time searching for files or fixing bugs caused by confusion. A good structure saves time, reduces errors, and makes adding new features easier. It also helps new team members get up to speed quickly.

Where it fits

Before learning folder structure, you should understand basic React concepts like components and props. After mastering folder structure, you can learn advanced topics like state management, routing, and testing. Folder structure is a foundation that supports all these later skills.

Mental Model

Core Idea

Organizing your React project folders like a well-arranged toolbox makes finding and fixing things fast and easy.

Think of it like...

Imagine your React project as a kitchen. If all utensils, ingredients, and tools are scattered randomly, cooking becomes slow and frustrating. But if knives are in one drawer, spices on a shelf, and pots in a cabinet, you can cook smoothly. Similarly, a good folder structure groups related files so you can work efficiently.

ProjectRoot
├── public
│   └── index.html
├── src
│   ├── assets
│   │   ├── images
│   │   └── styles
│   ├── components
│   │   ├── Button
│   │   │   ├── Button.jsx
│   │   │   └── Button.css
│   │   └── Header
│   │       ├── Header.jsx
│   │       └── Header.css
│   ├── pages
│   │   ├── Home.jsx
│   │   └── About.jsx
│   ├── hooks
│   ├── utils
│   ├── App.jsx
│   └── index.js
└── package.json

Build-Up - 7 Steps

1

Foundation

Understanding React Project Basics

Concept: Learn what files and folders are typically in a React project and their roles.

A React project usually has a 'public' folder for static files like HTML and images, and a 'src' folder where all React code lives. Inside 'src', you write components, styles, and helper functions. The entry point is often 'index.js' or 'index.jsx' which starts the app.

Result

You know where your app starts and where to put your React code.

Understanding the basic layout of a React project helps you see why organizing files matters.

2

Foundation

Grouping Files by Feature or Type

Concept: Learn the two main ways to organize folders: by feature or by file type.

Organizing by type means putting all components in one folder, all styles in another, and so on. Organizing by feature means grouping everything related to one feature (component, styles, tests) together. Both have pros and cons depending on project size.

Result

You can decide how to group files to keep your project tidy.

Knowing these two approaches helps you choose a structure that fits your project's needs.

3

Intermediate

Creating Component-Centric Folders

🤔Before reading on: Do you think each component should have its own folder or share a folder with others? Commit to your answer.

Concept: Learn to create a folder for each component containing its code, styles, and tests.

For example, a 'Button' component folder contains 'Button.jsx', 'Button.css', and 'Button.test.js'. This keeps everything related to that component in one place, making it easier to maintain and reuse.

Result

Your components are self-contained and easy to find or move.

Understanding that components are units of UI helps you organize code for better scalability and clarity.

4

Intermediate

Separating Pages and Shared Components

🤔Before reading on: Should pages and small reusable components live together or separately? Commit to your answer.

Concept: Learn to separate full pages (views) from smaller shared components.

Pages represent full screens like 'Home' or 'About' and go in a 'pages' folder. Smaller components like buttons or headers go in 'components'. This separation clarifies the app structure and routing.

Result

Your app structure clearly distinguishes between screens and reusable parts.

Knowing this separation helps manage complexity as your app grows.

5

Intermediate

Organizing Utilities and Hooks

Concept: Learn to keep helper functions and custom hooks in dedicated folders.

Utilities are reusable functions like formatting dates or API calls, placed in a 'utils' folder. Custom React hooks, which add special behavior, go in a 'hooks' folder. This keeps your code DRY (Don't Repeat Yourself) and organized.

Result

Helpers and hooks are easy to find and reuse across components.

Separating utilities and hooks prevents clutter and promotes code reuse.

6

Advanced

Scaling Folder Structure for Large Apps

🤔Before reading on: Do you think a flat folder structure works well for large apps? Commit to your answer.

Concept: Learn how to organize folders to handle many features and components in big projects.

Large apps often use a feature-based structure where each feature has its own folder with components, hooks, styles, and tests inside. This reduces confusion and makes teams work independently. Sometimes, folders are nested by domain or functionality.

Result

Your project stays manageable even as it grows very large.

Understanding scalable structures prevents chaos and supports teamwork in big projects.

7

Expert

Balancing Structure and Developer Experience

🤔Before reading on: Is the most deeply nested folder structure always the best? Commit to your answer.

Concept: Learn to balance strict organization with ease of use and speed of development.

Too many folders and files can slow you down and make navigation hard. Experts use conventions, index files, and tooling like path aliases to keep imports clean. They also adapt structure as the project evolves, not rigidly sticking to one pattern.

Result

You create a folder structure that is both organized and developer-friendly.

Knowing when to simplify or reorganize keeps your project healthy and your team happy.

Under the Hood

React itself does not enforce any folder structure; it only requires an entry point and components to render UI. The folder structure is a developer convention that helps tools like bundlers and editors work efficiently. Good structure improves module resolution, reduces import errors, and supports features like code splitting and lazy loading.

Why designed this way?

React was designed to be flexible and unopinionated about project layout to support many use cases. This freedom lets teams choose what fits best but also means best practices emerged from community experience rather than official rules. The tradeoff is balancing flexibility with maintainability.

Project Root
├── public (static files)
├── src (React code)
│   ├── components (UI pieces)
│   ├── pages (screens)
│   ├── hooks (custom logic)
│   ├── utils (helpers)
│   └── assets (images, styles)
└── package.json (project config)

Myth Busters - 4 Common Misconceptions

Quick: Do you think putting all components in one folder is always best? Commit yes or no.

Common Belief: All components should live in a single 'components' folder regardless of size.

Reality: For small projects this works, but large projects benefit from grouping components by feature or domain to avoid clutter.

Why it matters: Ignoring this leads to huge folders with hundreds of files, making it hard to find or update components.

Quick: Do you think deeply nested folders always improve clarity? Commit yes or no.

Common Belief: More folders and nesting always make the project more organized.

Reality: Excessive nesting can make navigation slow and imports complicated, hurting developer productivity.

Why it matters: Over-nesting causes frustration and slows down development, especially for new team members.

Quick: Do you think React enforces a folder structure? Commit yes or no.

Common Belief: React requires a specific folder structure to work correctly.

Reality: React does not enforce any folder structure; it only needs an entry point and components to render UI.

Why it matters: Believing this limits creativity and causes unnecessary complexity trying to fit a 'required' pattern.

Quick: Do you think styles should always be in a separate global folder? Commit yes or no.

Common Belief: All CSS or style files must be in one global folder separate from components.

Reality: Co-locating styles with components improves maintainability and clarity, especially with CSS modules or styled components.

Why it matters: Separating styles globally can cause confusion about which styles belong to which component.

Expert Zone

1

Using index.js files inside folders can simplify imports but may hide file locations, so balance clarity and convenience.

2

Path aliases configured in bundlers or TypeScript reduce long relative import paths, improving readability in deep folder structures.

3

Folder structure should evolve with the project; rigid early decisions can cause costly refactors later.

When NOT to use

Avoid complex feature-based folder structures for very small projects or prototypes where speed matters more than organization. Instead, use a simple flat structure. For monorepos or very large apps, consider splitting into multiple packages or apps instead of one huge folder tree.

Production Patterns

In real-world React apps, teams often combine feature-based folders with shared components and utilities. They use tooling like ESLint and Prettier to enforce consistent structure and naming. CI pipelines may check folder conventions. Large companies may have internal templates or generators to standardize structure across projects.

Connections

Modular Programming

Folder structure in React builds on modular programming principles by grouping related code together.

Understanding modular programming helps grasp why grouping components and utilities improves code reuse and maintainability.

Library Organization in Physical Stores

Both organize items by category and usage to help users find what they need quickly.

Seeing folder structure like organizing books by genre and author helps appreciate the importance of logical grouping.

Urban City Planning

Just as cities organize zones for homes, businesses, and parks, folder structures organize code by function and feature.

Knowing how city planning balances accessibility and growth helps understand why folder structures must balance clarity and scalability.

Common Pitfalls

#1 Mixing unrelated files in one folder causing confusion.

Wrong approach:

src/components/Button.jsx
src/components/utils.js
src/components/Home.jsx

Correct approach:

src/components/Button/Button.jsx
src/utils/helpers.js
src/pages/Home.jsx

Root cause:

Not separating concerns leads to folders with mixed responsibilities, making it hard to find or update files.

#2 Over-nesting folders making imports long and navigation slow.

Wrong approach:

src/features/user/profile/components/avatar/Button/Button.jsx

Correct approach:

src/features/user/profile/components/Button.jsx

Root cause:

Trying to be too granular with folders creates deep paths that slow development.

#3 Keeping styles in a global folder separate from components.

Wrong approach:

src/styles/Button.css
src/components/Button.jsx

Correct approach:

src/components/Button/Button.css
src/components/Button/Button.jsx

Root cause:

Separating styles from components breaks the connection between UI and its look, making maintenance harder.

Key Takeaways

A clear folder structure in React projects keeps code organized, easy to find, and maintainable.

Grouping files by feature or component helps scale projects and supports teamwork.

Avoid over-nesting folders to keep navigation and imports simple.

Co-locating component code, styles, and tests improves clarity and reduces errors.

Folder structure is flexible; adapt it as your project grows and your team’s needs change.

Practice

1. What is the main reason to organize React files into folders like components, pages, and hooks?

easy

A. To make the app run faster

B. To reduce the file size of the app

C. To keep the project easy to understand and maintain

D. To avoid using React hooks

Solution

1. Step 1: Understand folder organization purpose

   Folders like components and hooks group related files by their role.

2. Step 2: Recognize benefits of clear structure

   This grouping makes the project easier to read and maintain for developers.

3. Final Answer:

   To keep the project easy to understand and maintain -> Option C

4. Quick Check:

   Folder organization = easier maintenance [OK]

Hint: Folders group related files for clarity and ease [OK]

Common Mistakes:

• Thinking folder structure affects app speed
• Confusing file size with organization
• Believing hooks folder is optional for React hooks

2. Which of the following is the correct way to organize a React project folder for components?

easy

A. Put all components in a single components folder

B. Scatter components randomly in the root folder

C. Put components inside the public folder

D. Put components inside the node_modules folder

Solution

1. Step 1: Identify standard folder for components

   React projects usually keep components in a dedicated components folder.

2. Step 2: Avoid incorrect placements

   Components should not be in public or node_modules folders, which serve other purposes.

3. Final Answer:

   Put all components in a single components folder -> Option A

4. Quick Check:

   Components folder = centralized components [OK]

Hint: Keep components together in one folder [OK]

Common Mistakes:

• Placing components in public folder
• Scattering components without structure
• Modifying node_modules folder

3. Given this folder structure:

src/
  components/
    Button.jsx
  hooks/
    useToggle.js
  pages/
    Home.jsx

Which file would you expect to find the custom React hook?

medium

A. src/components/Button.jsx

B. src/pages/Home.jsx

C. src/index.js

D. src/hooks/useToggle.js

Solution

1. Step 1: Understand folder naming conventions

   Custom hooks are usually placed in the hooks folder.

2. Step 2: Match file to folder purpose

   The file useToggle.js inside hooks matches the custom hook naming pattern.

3. Final Answer:

   src/hooks/useToggle.js -> Option D

4. Quick Check:

   Custom hooks in hooks folder = useToggle.js [OK]

Hint: Hooks go in the hooks folder [OK]

Common Mistakes:

• Looking for hooks in components folder
• Confusing pages folder with hooks
• Assuming index.js contains hooks

4. You see this folder structure in a React project:

src/
  components/
    Header.jsx
  utils/
    helpers.js
  Header.jsx

What is the main problem here?

medium

A. Having a utils folder is not recommended

B. Duplicate Header.jsx file in root and components folder causes confusion

C. Components should be inside utils folder

D. Files should not have .jsx extension

Solution

1. Step 1: Identify duplicate file names

   There are two Header.jsx files: one in components and one in root.

2. Step 2: Understand confusion caused by duplicates

   This duplication can confuse developers and cause import errors.

3. Final Answer:

   Duplicate Header.jsx file in root and components folder causes confusion -> Option B

4. Quick Check:

   Duplicate filenames = confusion [OK]

Hint: Avoid duplicate filenames in different folders [OK]

Common Mistakes:

• Thinking utils folder is bad practice
• Believing components belong in utils
• Ignoring file extensions importance

5. You are building a large React app. Which folder structure best supports growth and easy maintenance?

hard

A. Organize by feature: each feature folder contains components, hooks, and styles

B. Put all files in one big folder to avoid complexity

C. Separate files only by file type, ignoring features

D. Keep all components and hooks mixed in the root folder

Solution

1. Step 1: Understand feature-based organization

   Grouping by feature means each feature folder holds all related files, making it easier to find and update.

2. Step 2: Compare with other structures

   Flat or type-only folders become hard to manage as app grows, causing confusion.

3. Final Answer:

   Organize by feature: each feature folder contains components, hooks, and styles -> Option A

4. Quick Check:

   Feature folders = scalable and maintainable [OK]

Hint: Group by feature for scalable projects [OK]

Common Mistakes:

• Using one big folder causes clutter
• Separating only by file type slows feature updates
• Mixing all files in root is confusing