React Setup Guide: Install, Create, and Run a React Project

Introduction to React Setup

Before building React applications, you need a development environment that can run JavaScript tools, install dependencies, compile JSX, and serve your application locally. A typical React setup includes Node.js, npm, a project scaffold such as Vite, and a code editor.

Vite provides a development server with fast startup and hot module replacement, allowing you to see many code changes without manually refreshing the browser. It also provides a production build command that bundles your application for deployment.

This guide uses React with JavaScript and Vite. You can also create a TypeScript-based project when you want static type checking. If you are new to React, first review the React introduction to understand components, JSX, props, and state.

Step 1: Install Node.js and npm

Node.js is a JavaScript runtime used by development tools and build systems. npm is the package manager distributed with Node.js and is commonly used to install React, Vite, and other project dependencies.

1. Visit the official Node.js website.
2. Download an appropriate supported LTS release for your operating system.
3. Run the installer and follow the installation instructions.
4. Open a new terminal after installation completes.

Verify that Node.js and npm are available by running these commands:

node --version
npm --version

Both commands should print version numbers. If the terminal reports that a command cannot be found, check the installation and your system's PATH configuration before continuing.

Step 2: Create a React Project with Vite

Vite provides a starter template that includes the basic files and configuration needed to develop a React application. Run the following commands in your terminal to create a JavaScript project:

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

The first command creates a project named my-react-app using Vite's React template. The second command enters the project directory, and the third installs the dependencies listed in package.json.

If you prefer to select a template interactively, run npm create vite@latest and follow the prompts. Select React and then choose JavaScript or TypeScript according to your project requirements.

Step 3: Start the Development Server

After installing the dependencies, start Vite's development server with the following command:

npm run dev

The terminal displays a local URL, commonly http://localhost:5173/. Open the URL in your browser to view the starter application. If the port is already occupied, Vite may choose another available port and display that address in the terminal.

Keep the terminal running while developing. Stop the server with Ctrl+C when you want to shut it down.

Step 4: Understand the Project Structure

A newly generated Vite React project contains application source files, public assets, dependency metadata, and development configuration. The exact file structure can vary between template versions.

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

• public/: Contains static assets that can be served directly without being imported into the module graph.
• src/: Contains the application's source code, including components, styles, and JavaScript modules.
• src/App.jsx: Commonly contains the root application component in the starter template.
• src/main.jsx: Entry point that creates the React root and renders the application.
• index.html: HTML document containing the root element where React mounts.
• package.json: Stores project metadata, scripts, and dependency declarations.
• package-lock.json: Records the resolved npm dependency tree to support reproducible installations.
• vite.config.js: Holds Vite configuration when the project needs customization.

Step 5: Understand the React Entry Point

The entry point connects your React component tree to the HTML document. In a standard Vite React project, main.jsx imports the root component, finds the root HTML element, and asks React to render the application there.

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

The createRoot() function creates a React root for the application. The render() method displays the component tree inside that root. StrictMode enables additional development-time checks that help identify certain problems; it does not render an extra visible wrapper in the DOM.

The corresponding HTML document contains an element with the matching ID:

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

React renders the component tree into this element. If the ID in the JavaScript does not match the element in the HTML document, the application will not mount correctly.

Step 6: Build Your First Component

Open src/App.jsx and replace the starter component with a simple component of your own. A function component returns JSX that describes the UI React should render.

function Welcome() {
  return (
    <section>
      <h1>Welcome to React</h1>
      <p>Your React development environment is ready.</p>
    </section>
  );
}

export default function App() {
  return (
    <main>
      <Welcome />
    </main>
  );
}

Save the file and return to the browser. Vite's development server should update the page automatically. This development workflow is often called hot module replacement because the tooling can update changed modules without requiring a complete manual reload.

Learn how to structure reusable UI in the React components guide and how to write JSX in the JSX tutorial.

Step 7: Understand npm Scripts

The scripts section of package.json defines commands for common development tasks. A typical Vite React template includes scripts similar to these:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

• npm run dev starts the local development server.
• npm run build creates an optimized production build.
• npm run lint runs the configured linting tool when that script is present.
• npm run preview serves the production build locally for verification.

These scripts are examples; the actual commands depend on the generated template and any changes you make to package.json. Always check the scripts in your own project before running them.

Step 8: Add Components and Styles

As your application grows, create separate files for components that have clear responsibilities. For example, a navigation bar, profile card, and footer can each be implemented independently and imported into the root component.

// src/components/ProfileCard.jsx
export default function ProfileCard() {
  return (
    <article className="profile-card">
      <h2>Developer Profile</h2>
      <p>Learning React one component at a time.</p>
    </article>
  );
}

// src/App.jsx
import ProfileCard from './components/ProfileCard.jsx';

export default function App() {
  return (
    <main>
      <h1>My Application</h1>
      <ProfileCard />
    </main>
  );
}

React uses className rather than the HTML class attribute in JSX. You can define the corresponding CSS rules in a stylesheet and import that stylesheet into your application. For additional approaches, explore the React styling guide.

Step 9: Install Additional Packages

Most React projects use additional packages for specific needs, such as routing, testing, form validation, or data fetching. Install a package from the project directory using npm, then import its APIs where required.

npm install react-router-dom

This command installs React Router DOM, a library used for client-side routing in browser applications. Choose dependencies based on actual requirements rather than installing every available library at the beginning.

When adding a dependency, review its documentation, supported React versions, maintenance status, and impact on the production bundle. Learn more in the React Router guide.

Step 10: Create a Production Build

The development server is intended for local development. Before deployment, create a production build that applies the configured build optimizations.

npm run build
npm run preview

Vite typically writes the generated production files to the dist directory. The preview command lets you inspect the built application locally. It is intended for verification rather than as a production server.

Test the production build before publishing it, especially if your application uses client-side routing, environment variables, API endpoints, or dynamically loaded assets. Follow the React deployment guide for the next steps.

Common Setup Problems

• Node.js or npm is not recognized: Confirm that Node.js is installed, reopen the terminal, and check the PATH configuration.
• Dependency installation fails: Verify your Node.js version, network access, and npm configuration. Review the error output before removing lockfiles or changing dependency versions.
• The development server uses another port: Vite may automatically select an available port. Open the URL printed in the terminal.
• The browser displays a blank page: Inspect the browser console and terminal for import errors, syntax errors, or a mismatch between the root element ID and the entry point.
• Changes do not appear: Save the file, check that the development server is running, and inspect terminal or browser errors.
• Production routes return a not-found response: Configure your hosting provider to serve the application entry point for routes that should be handled by the client-side router.
• Environment variables are missing: Follow Vite's environment-variable conventions and avoid placing secrets in client-side variables because browser-delivered values are visible to users.

React Setup Best Practices

• Use a supported Node.js LTS version compatible with your tooling.
• Keep dependencies and lockfiles under version control.
• Use separate components for distinct interface responsibilities.
• Organize source files consistently as the application grows.
• Keep API credentials and other secrets on the server, not in browser code.
• Use environment variables for public configuration that differs between environments.
• Run linting and production builds before deployment when those scripts are configured.
• Test the built application, not just the development server.
• Choose additional libraries deliberately and review their maintenance and compatibility.

Conclusion

Setting up React involves installing Node.js, creating a project, installing dependencies, understanding the entry point, and starting the development server. Vite simplifies this workflow by providing a ready-to-use React template and production build tools.

Once your environment is ready, focus on building components and learning JSX, props, state, and event handling. Continue with the React components tutorial, state management, and React with TypeScript.