1. Introduction

After setting up the React development environment, the next step is to understand how a React application is organized and how it runs in a web browser.

A React project contains several files and folders, each serving a specific purpose. Understanding this structure helps developers write organized code, locate errors, manage components, and maintain applications as they grow.

In this tutorial, you will explore the standard project structure generated by Vite, understand the role of important files, learn how React renders an application, and build your first customized React interface.

By the end of this tutorial, you will be able to navigate a React project confidently and make basic changes to your application's user interface.

2. Learning Objectives

After completing this tutorial, you will be able to:

• Understand the folder structure of a Vite React project.

• Identify the purpose of important React files.

• Understand the relationship between index.html, main.jsx, and App.jsx.

• Explain how React renders a component in the browser.

• Customize your first React application.

• Run and troubleshoot a React development server.

• Follow a basic workflow for developing React applications.

3. Core Concepts and Explanation

3.1 Understanding the React Project Structure

When you create a React project using Vite, the generated project contains a set of files and directories that help organize your application.

A typical Vite React project looks like this:

my-react-app/
├── node_modules/
├── public/
│   └── vite.svg
├── src/
│   ├── assets/
│   ├── App.css
│   ├── App.jsx
│   ├── index.css
│   └── main.jsx
├── .gitignore
├── index.html
├── package.json
├── package-lock.json
└── vite.config.js

The exact structure and starter files may differ between Vite versions or templates.

Let's understand the important files and folders.

3.2 The node_modules Folder

The node_modules directory contains the packages installed for your project, including React, React DOM, Vite, and other dependencies.

For example, when you run:

npm install

npm reads the project's dependency information and installs the required packages.

Important points:

• Do not manually edit dependency files inside node_modules.

• This directory is generally not committed to Git.

• It can be recreated by installing the dependencies again.

3.3 The public Folder

The public directory stores static files that need to be served directly, such as certain images, icons, or other public assets.

For example:

public/
├── favicon.ico
└── robots.txt

Files placed in Vite's public directory are served from the root URL.

If you have a file named logo.png inside public, you can reference it using:

<img src="/logo.png" alt="Company logo" />

Use the public directory when you need a file to retain a predictable public URL. For assets imported into components, the src/assets directory is often a better choice.

3.4 The src Folder

The src directory contains the main application source code.

It commonly includes:

• React components.

• CSS stylesheets.

• JavaScript modules.

• Imported images and other assets.

• Application logic.

As your application grows, you can organize this directory into subfolders such as components, pages, hooks, and services.

For example:

src/
├── components/
├── pages/
├── assets/
├── App.jsx
├── App.css
├── index.css
└── main.jsx

These additional folders are organizational choices, not mandatory React requirements.

3.5 Understanding App.jsx

The App.jsx file commonly contains the main application component in a Vite React starter project.

A component is a reusable part of the user interface.

Example:

function App() {
  return (
    <div>
      <h1>Welcome to React</h1>
      <p>This is my first React application.</p>
    </div>
  );
}

export default App;

Explanation:

1. function App() defines a JavaScript function named App.

2. The return statement describes the user interface using JSX.

3. The <h1> element displays the heading.

4. The <p> element displays supporting text.

5. export default App makes the component available to other modules through an import.

React components conventionally use PascalCase names, such as App, Header, and ProductCard.

3.6 Understanding main.jsx

The main.jsx file acts as the entry point for the React application in the standard Vite React template.

It typically imports React DOM, the main application component, and a stylesheet.

Example:

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>
);

Let's understand the important parts.

import { createRoot } from 'react-dom/client'

This imports the API used to create a React root for rendering into a browser DOM element.

document.getElementById('root')

This finds the HTML element whose ID is root.

createRoot(...)

This creates a React root associated with that element.

.render(...)

This tells React to render the supplied React element tree into the root.

StrictMode

This enables additional development-time checks for certain React issues. In development, it may cause some functions or effects to run more than once to help reveal problems. It does not represent a separate visible section of the user interface.

3.7 Understanding index.html

The index.html file provides the HTML document used by Vite.

A simplified example is:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My React App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

The important element is:

<div id="root"></div>

It provides the HTML container into which React renders the application's user interface.

The module script loads main.jsx, which imports and renders the App component.

Important distinction: React does not replace the entire HTML document. It renders and updates the interface within the root container you provide.

3.8 Understanding package.json

The package.json file contains project metadata, dependencies, and scripts.

A simplified example:

{
  "name": "my-react-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Your actual file will contain additional information, including dependencies.

The scripts provide convenient commands:

Command	Purpose
npm run dev	Starts the development server
npm run build	Creates a production build
npm run preview	Previews the production build locally

3.9 How a React Application Runs

The basic flow of a standard Vite React application is:

1. You run npm run dev in the terminal.

2. Vite starts the development server.

3. The browser requests the application's HTML document.

4. The module script loads main.jsx.

5. main.jsx imports the App component and its dependencies.

6. React DOM renders the component tree inside the root container.

7. The browser displays the resulting user interface.

8. When you save supported source-code changes, Vite can update the page through its development features.

The relationship can be summarized as:

index.html
    |
    v
main.jsx
    |
    v
App.jsx
    |
    v
React renders the UI
    |
    v
Browser displays the application

This is a simplified learning model. A larger application may contain many components, routes, providers, and additional modules.

4. Practical Code Examples

Example 1: Run Your Existing React Application

Open the project folder in VS Code.

Open the integrated terminal and run:

npm install
npm run dev

Open the local URL printed in the terminal.

You should see the starter Vite React application.

Expected result: The browser displays the initial application, and the terminal continues running the development server.

Example 2: Create Your First Custom React Application

Now replace the starter component with a simple customized interface.

Step 1: Open src/App.jsx

Replace its contents with:

function App() {
  return (
    <main>
      <h1>Welcome to Param Classes</h1>
      <p>Learn React.js step by step.</p>
      <button>Start Learning</button>
    </main>
  );
}

export default App;

Step 2: Open src/App.css

Replace its contents with:

main {
  max-width: 700px;
  margin: 80px auto;
  padding: 32px;
  text-align: center;
  font-family: Arial, sans-serif;
}

h1 {
  color: #087ea4;
  font-size: 36px;
}

p {
  color: #444;
  font-size: 18px;
}

button {
  padding: 12px 20px;
  border: none;
  border-radius: 8px;
  background-color: #087ea4;
  color: white;
  font-size: 16px;
  cursor: pointer;
}

Step 3: Open src/index.css

If you want to remove the default starter styling, replace its contents with:

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  background-color: #f4f8fb;
}

Step 4: Make sure App.css is imported

Add this line near the top of App.jsx:

import './App.css';

Your complete App.jsx should now be:

import './App.css';

function App() {
  return (
    <main>
      <h1>Welcome to Param Classes</h1>
      <p>Learn React.js step by step.</p>
      <button>Start Learning</button>
    </main>
  );
}

export default App;

Expected browser output:

• A large blue heading displaying “Welcome to Param Classes”.

• A paragraph displaying “Learn React.js step by step.”

• A blue “Start Learning” button.

• A light background and a centered layout.

The button is visual only at this stage. It will not perform an action until you add event handling in a later tutorial.

Example 3: Understand the React Entry Point

Consider this code from main.jsx:

import { createRoot } from 'react-dom/client';
import App from './App.jsx';

const rootElement = document.getElementById('root');

const root = createRoot(rootElement);

root.render(<App />);

Step-by-step explanation:

1. Import createRoot from React DOM.

2. Import the App component.

3. Locate the HTML element with the ID root.

4. Create a React root associated with that element.

5. Render the App component into that root.

This example demonstrates the essential rendering process without the optional StrictMode wrapper.

It assumes that index.html contains an element with id="root" and that the application has been configured correctly.

Example 4: Make a Change and Observe It

With the development server running, change the heading in App.jsx:

<h1>My First React Project</h1>

Save the file.

Vite will normally update the browser automatically when the relevant source changes are supported by its hot-update system.

Expected result: The browser displays the updated heading without requiring you to manually rebuild the application.

5. Real-World Applications

Understanding the project structure becomes increasingly important as applications grow.

E-commerce Application

A project may use folders such as:

src/
├── components/
│   ├── Navbar.jsx
│   └── ProductCard.jsx
├── pages/
│   ├── Home.jsx
│   └── Products.jsx
├── assets/
├── App.jsx
└── main.jsx

This separation helps developers organize reusable interface components and page-level components.

Admin Dashboard

An admin dashboard might contain:

• Shared navigation and sidebar components.

• Dashboard pages and data tables.

• Reusable chart components.

• API service modules.

• Global styles and assets.

Keeping these concerns organized makes the codebase easier to understand and maintain.

Team Development

When multiple developers work on the same application, a consistent project structure helps them locate files, understand responsibilities, review changes, and collaborate more effectively.

The folder structure should serve the application's needs. You do not need to create every possible folder when starting a small project.

6. Common Mistakes and Best Practices

Common Mistakes

Mistake 1: Changing the root element ID

If main.jsx looks for root, but index.html contains a different ID, React will not find the expected container.

Solution: Make sure the ID in document.getElementById(...) matches the HTML element.

Mistake 2: Forgetting to export a component

If another file imports App as a default export, but App.jsx does not provide one, the import will fail.

Solution: Check that the component is exported correctly.

Mistake 3: Incorrect import paths

An import such as ./App.jsx must point to the correct file relative to the importing module.

Solution: Verify the folder location, file name, and extension where applicable.

Mistake 4: Putting application JSX directly into index.html

React applications normally keep their component interface in React source files rather than manually writing the whole interface into the root container.

Solution: Build the interface in components and render those components through the React entry point.

Mistake 5: Editing the wrong stylesheet

A CSS change may not appear if the stylesheet is not imported or if another CSS rule overrides it.

Solution: Verify imports, inspect the relevant selectors, and check the browser's developer tools when necessary.

Mistake 6: Closing the development server

If you stop the terminal process running Vite, the local development server will no longer serve the application.

Solution: Restart it using npm run dev.

Best Practices

• Keep application source code inside src.

• Create reusable components when the interface begins to repeat.

• Use meaningful file and component names.

• Keep styling organized and avoid unnecessary duplication.

• Understand the role of the entry point before modifying it.

• Avoid editing generated dependency files.

• Use Git to track important source-code changes.

• Test the production build before deployment.

7. Practice Exercises

Exercise 1: Explore the Project

Open a Vite React project and locate these files:

• index.html

• src/main.jsx

• src/App.jsx

• src/index.css

• package.json

Write one sentence explaining the purpose of each file.

Exercise 2: Customize the Interface

Modify App.jsx to display:

• Your own heading.

• A short paragraph.

• A button labeled “Explore Courses”.

Use CSS to center the content and improve its appearance.

Exercise 3: Trace the Rendering Flow

Explain how the application moves from index.html to main.jsx and then to App.jsx.

Try to explain the purpose of the root container in your own words.

Exercise 4: Add a Component

Create a new file named src/components/Welcome.jsx.

Write a functional component that returns a heading and a paragraph. Export it and import it into App.jsx.

Exercise 5: Troubleshoot the Root Container

Suppose main.jsx uses:

document.getElementById('root')

But index.html contains:

<div id="app"></div>

Identify the problem and describe the correction required.

8. Key Takeaways and Conclusion

In this tutorial, you learned how a Vite React project is structured and how its files work together to render a user interface.

Remember these key points:

• index.html provides the document and root container.

• main.jsx initializes the React root and renders the application.

• App.jsx commonly contains the main application component.

• App.css and index.css can hold component-level and global styling.

• package.json defines project metadata, dependencies, and scripts.

• Vite provides the development server and build tooling.

• React DOM renders the component tree into the browser's DOM.

Understanding these fundamentals makes it easier to create, organize, debug, and expand React applications.