React Project Folder Structure: Don’t Get Lost in the src/ and public/ Jungle

Hello to every <div> warrior and useState() wizard out there!

You’ve just finished npx create-react-app and—BOOM—your editor explodes with folders and files whose names sound like cryptic spells: index.js, App.test.js, manifest.json, and the infamous serviceWorker.js. Don’t panic. Grab your favorite beverage, sit back, and let’s casually explore what each piece does, why it exists, and how you can keep everything tidy as your project grows.

 

The Basic Blueprint of a React Project

A freshly scaffolded Create React App (CRA) project typically looks like this:

my-react-app/
├── node_modules/
├── public/
│   ├── favicon.ico
│   ├── index.html
│   └── manifest.json
├── src/
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── index.css
│   ├── index.js
│   └── reportWebVitals.js
├── .gitignore
├── package.json
├── README.md
└── yarn.lock / package-lock.json

Let’s walk through each part—think of it as a guided tour through a newly built house you might one day remodel.

 

node_modules/ — The Big Warehouse

This enormous folder is where every external library you install (via npm or yarn) is stored. It’s like a warehouse stocked with parts you might need to build furniture later. The rule of thumb: never manually edit anything here. If something breaks inside, you fix it by updating or reinstalling via your package manager—let the “warehouse staff” do the heavy lifting.

 

public/ — Your Project’s Front Door

The public directory contains static assets—files sent directly to the browser without processing by React. There are three MVPs (Most Valuable Pieces) here:

index.html

This is the only HTML file you serve. React injects your entire component tree into the <div id="root"></div> in this file, enabling SPA magic (one HTML file that can “become” many pages thanks to React Router).

manifest.json

If you ever want to convert your web app into a Progressive Web App (PWA), this JSON is your best friend. It defines your app’s name, icons, theme colors, and how it should behave when users “install” it on their phone.

favicon.ico

The tiny tab icon we all love to customize. Swap it out with your brand logo to keep things professional.

 

src/ — Where the Magic Happens

Everything you actively code lives here: components, hooks, styles, images, utilities—basically your entire React kingdom.

index.js

The entry point that mounts your React app. A minimal example:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

You rarely need to edit this file, but knowing what it does helps you debug render issues.

App.js

Your root component—the head chef orchestrating every other dish. You might start with something like:

function App() {
  return (
    <div className="App">
      <h1>Hello React World!</h1>
    </div>
  );
}
export default App;

Most beginners gradually break App.js into smaller, reusable components (Navbar, Footer, Card, etc.).

App.css & index.css

Pre‑generated styles. Feel free to ditch them in favor of Tailwind, CSS Modules, Sass, or styled‑components—whatever matches your flavor.

App.test.js

A basic Jest test file. You can ignore it early on, but once your project grows, tests become your bug‑slaying sword.

reportWebVitals.js

Optional performance measuring. Hook it into Google Analytics or simply delete if you’re not tracking Core Web Vitals yet.

 

Optional Custom Folders

src/
├── assets/       # images, icons, fonts
├── components/   # reusable UI pieces
├── pages/        # route-level views (Home, About, etc.)
├── hooks/        # custom React hooks
├── context/      # React Context providers
└── utils/        # helper functions

This modular structure makes your codebase easier to navigate and scale, especially in team settings.

 

package.json — The Project Passport

Think of package.json as your app’s identification card. It lists:

• Metadata: name, version, author
• Scripts: commands like npm start, npm run build, npm test
• Dependencies: packages required in production
• DevDependencies: tooling needed only during development

Example snippet:

{
  "name": "my-react-app",
  "version": "0.1.0",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

 

README.md — Your Friendly Instruction Manual

CRA ships a default README that explains how to run, build, and test your project. Over time, update it with environment variable docs, architecture diagrams, or onboarding steps for new teammates.

 

.gitignore — The Do‑Not‑Track List

This file tells Git which files or folders to leave out of version control—typically:

node_modules
build
.env

 

package-lock.json / yarn.lock — Version Stability Guards

Lockfiles ensure every developer on your team installs the exact same dependency versions—reducing “works‑on‑my‑machine” headaches.

 

Scaling Up: Structuring Larger Projects

As your codebase balloons, it pays to group logic by domain rather than file type. A popular enterprise‑friendly layout:

src/
├── components/
│   ├── Navbar/
│   │   ├── Navbar.js
│   │   └── Navbar.module.css
│   └── Button/
├── pages/
│   ├── Home.js
│   └── About.js
├── hooks/
│   └── useWindowSize.js
├── context/
│   └── AuthContext.js
├── services/
│   └── api.js
├── utils/
│   └── helpers.js
├── App.js
└── index.js

This “feature‑based” organization keeps related logic together, making collaboration smoother and refactors less painful.

 

Tips for a Cleaner Codebase

• Absolute Imports: Create a jsconfig.json (or tsconfig.json) with "baseUrl": "src" so you can import Button from "components/Button" instead of ../../../components/Button.
• Environment Variables: Prefix custom keys with REACT_APP_ inside .env files for secure configs (e.g., REACT_APP_API_URL).
• Prop‑Drilling Pain? Reach for Context API or a state manager like Redux, Zustand, or Recoil.
• Code Splitting: Use React’s lazy and Suspense to load heavy components on demand and speed up initial page load.
• Testing Strategy: Write small unit tests with Jest, component tests with React Testing Library, and e2e flows with Cypress.

At first glance, a React project’s folder layout looks intimidating, but each file serves a purposeful role. Mastering this structure will save you hours of confusion, bolster team collaboration, and pave the way for effortless scaling.

“React is like a giant box of LEGO bricks—once you know the difference between a foundation plate and a roof tile, you can build anything.”