Understanding React Project Structure

Table of Contents +

You just finished Creating Your First React App, and Vite dropped a pile of files into your project. Feeling a little lost is normal, so let’s see what each one does.

🤔 Why Should You Care About the File Structure?

Here is the pain you hit on day one:

  • You open your brand new React project and see folders like node_modules and files like vite.config.js.
  • You have no idea where your actual code goes, so you do not even know which file to touch.
  • So you guess. Then you edit the wrong file, nothing changes on screen, and you start to wonder if you broke something.

A quick tour fixes all of that:

  • Once you know where your code lives, you will know exactly which file to open.
  • You will also know which files to leave alone, so you stop guessing.

🗺️ The Big Picture

When Vite finishes creating your app, your project folder looks something like this. Take a quick look first. Then we will walk through it piece by piece.

my-react-app/
├── node_modules/        # installed packages (do not edit)
├── public/              # static files served as-is
│   └── vite.svg
├── src/                 # YOUR code lives here
│   ├── assets/
│   │   └── react.svg
│   ├── App.css
│   ├── App.jsx          # the main component you edit
│   ├── index.css
│   └── main.jsx         # the entry point
├── .gitignore
├── index.html           # the single HTML page
├── package.json         # project info, dependencies, scripts
├── package-lock.json
└── vite.config.js       # Vite settings

Do not worry about memorizing every line. Most days you will only touch the src folder. Let us go through the important ones now.

📦 package.json — The Project’s ID Card

Think of package.json like the ID card for your project. It is a small file that holds the basic facts:

  • It has the project’s name and its version, so these are just labels for the project.
  • It has the list of packages your app needs, plus a few shortcut commands.
  • The word dependencies here means the outside packages your app needs to run, like React itself.

Here is a trimmed version of what is inside.

{
  "name": "my-react-app",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

Let me point out the parts you will actually use.

  • scripts are shortcut commands. When you run npm run dev, npm looks here and finds that dev means vite. So it starts the dev server.
  • dependencies are the packages your app needs to run, like react and react-dom.
  • name and version are just labels for the project.

Tip

When someone shares a React project with you, the first file to open is package.json. The scripts section tells you how to start it (usually npm run dev). The dependencies section tells you what it is built with.

📄 index.html — The One and Only Page

Here is something that surprises a lot of people. A React app has just one HTML page. That is it. Open index.html and you will see it is almost empty.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My React App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

The line that matters is <div id="root"></div>. Here is what it does:

  • That empty <div> is the box React will fill with your whole app.
  • Right now it is empty. But the moment your app runs, React reaches in and builds everything inside it.
  • The <script> line below it loads your code, so that filling-in can happen.

Note

You almost never edit index.html. The only common change is the text inside <title>, which sets the name shown on the browser tab.

📁 The src Folder — Where Your Code Lives

The src folder (short for “source”) is your home base. Here is why you will live in this folder:

  • This is where you will spend almost all of your time, so every component you write goes here.
  • Every style file and every image you import in code goes here too.
  • When you change something inside src, that is when you see your app change on screen.

Inside it, two files do the most important work: main.jsx and App.jsx. Let us look at both.

🚪 main.jsx — The Entry Point

main.jsx is the entry point of your app. That just means it is the very first piece of your code that runs. Its one job is to take your main component and put it inside that empty root div from index.html.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.jsx";
import "./index.css";


createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Read it top to bottom and it tells a simple story.

  • The imports bring in the tools React needs, your App component, and your global styles from index.css.
  • document.getElementById("root") grabs that empty <div id="root"> from the HTML page.
  • createRoot(...).render(...) tells React to take your App component and draw it inside that div.
  • <StrictMode> is just a helper wrapper that warns you about common mistakes while you build. It does not change what users see.

So this small file is the bridge. The HTML page has an empty box, and main.jsx fills that box with your React app. Here is that flow as a tiny diagram.

renders int

index.html

empty root div

main.jsx

entry point

App.jsx

your app

🧩 App.jsx — The Component You Actually Edit

App.jsx is your main component. It is the file you will edit the most. A component is a reusable piece of your interface written as a function that returns some markup. When you start building, you usually start here.

function App() {
  return (
    <div>
      <h1>Hello, React!</h1>
      <p>This is my first component.</p>
    </div>
  );
}


export default App;

Here is what is going on.

  • App is a normal JavaScript function. The only special thing is it returns markup that looks like HTML (that is JSX).
  • Whatever you put in that returned markup is what shows up on screen.
  • export default App lets other files import it. That is exactly what main.jsx did above.

Change the text inside that <h1>, save the file, and the browser updates right away. This instant update is what makes building with React feel quick.

🌐 The public Folder — Static Files

The public folder holds files that get served exactly as they are, without React touching them. Here is how to think about it:

  • It is the home for things like an image, a favicon, or a plain text file.
  • If you drop logo.png into public, you can use it in your app at the path /logo.png.
  • The difference from src is simple: files in src get processed and bundled, but files in public are handed to the browser unchanged.

Tip

Put images you import in code inside src/assets. Put files that need a fixed, predictable URL (like a favicon or a downloadable PDF) inside public.

🚫 node_modules — Do Not Edit This Folder

The node_modules folder is where all your installed packages actually live. Here is what is happening in there:

  • When you ran the install command, npm downloaded React and everything React itself needs and dropped it all in here.
  • That is why this folder is huge, with thousands of files.

The rule to remember is: never edit anything inside node_modules. A few more things follow from that:

  • You also never add it to Git, and you never need to read through it.
  • If it ever gets messed up, you just delete it and run npm install again to rebuild it from your package.json.

📋 Quick Reference

Here is the whole tour in one table you can come back to later.

File or Folder What It Is For Do You Edit It?
package.json Project info, dependencies, scripts Sometimes
index.html The single HTML page with the root div Rarely
src/ Where all your code lives Yes, all the time
src/main.jsx Entry point that renders App into root Rarely
src/App.jsx The main component you build on Yes, often
public/ Static files served as-is Sometimes
node_modules/ Installed packages Never

⚠️ Common Mistakes

A few mix-ups trip up almost everyone at the start. Watch out for these.

  • Editing index.html to add page content. Your content goes in components inside src, not in the HTML file.
  • Trying to edit files inside node_modules to fix a package. That folder is generated, so any change is wiped the next time you install.
  • Putting an image in public and then importing it in code like import logo from "/logo.png". Imported images belong in src/assets. Files in public are used by their URL path, not by importing.
  • Renaming or deleting the root div in index.html. main.jsx looks for that exact id, so removing it means your app has nowhere to render.

✅ Best Practices

These small habits keep your project tidy and easy to work in.

  • Keep all your code inside src so the structure stays predictable.
  • Leave main.jsx mostly alone. Build your screens by editing and adding components, starting from App.jsx.
  • Add node_modules to your .gitignore (Vite already does this for you) so you never commit it.
  • Use package.json as your map. When you are unsure how to run or build a project, check the scripts section first.

🧩 What You’ve Learned

A quick recap of the tour.

  • ✅ package.json is the project’s ID card. It holds the name, dependencies, and the scripts you run.
  • ✅ index.html is the single page, and its empty root div is where React puts your whole app.
  • ✅ The src folder is where your code lives and where you spend almost all your time.
  • ✅ main.jsx is the entry point that renders App into the root div.
  • ✅ App.jsx is the main component you edit and build on.
  • ✅ public holds static files served as-is, and node_modules holds installed packages you never edit.

Check Your Knowledge

Test what you learned. Pick an answer for each question, then click Check.

  1. 1

    Which folder is where you write almost all of your own code?

    Why: The src folder is your home base where components, styles, and code-imported assets live.

  2. 2

    What is the job of the empty root div in index.html?

    Why: main.jsx finds that div by its id and renders your App component inside it.

  3. 3

    Which file is the entry point that renders App into the root div?

    Why: main.jsx grabs the root div and calls createRoot to mount your App.

  4. 4

    What should you do with the node_modules folder?

    Why: node_modules is generated by npm install, so you never edit it and never commit it.

Score: 0 / 4

🚀 What’s Next?

Now the project is no longer a mystery. You know which files matter. It is time to actually start it up and see it live in the browser.

Running a React Application

Previous Creating Your First React App Next Running a React Application

Share & Connect

Share on LinkedIn