React

Installation & Project Setup 🛠️

1. Introduction 👋

Before you can start building with React, you need a properly configured development environment. This tutorial walks you through everything required to go from an empty machine to a running React application — including installing Node.js, choosing a package manager, scaffolding a project, and configuring essential development tools.

Information

This guide covers modern React tooling (as of 2026), with a focus on Vite and Next.js as the recommended project setup paths.

2. System Requirements 💻

React itself has minimal requirements, but the surrounding tooling ecosystem depends on a properly configured runtime environment.

Requirement	Minimum	Recommended
Operating System	Windows 10, macOS 11, Linux	Latest stable release
Node.js	18.x	20.x LTS or newer
RAM	4 GB	8 GB or more
Disk Space	1 GB free	5 GB+ free (for dependencies & caches)
Code Editor	Any text editor	VS Code with React/ESLint extensions

3. Installing Node.js 📦

Node.js is a JavaScript runtime required to run build tools, package managers, and development servers. It also ships with npm, the default Node.js package manager.

Windows

macOS

Linux

Download the LTS installer from the official Node.js website and run it. Alternatively, install via winget:

Code Snippet

winget install OpenJS.NodeJS.LTS

Install using Homebrew:

Code Snippet

brew install node

Use your distribution's package manager, or a version manager like nvm:

Code Snippet

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

Tip

Using a version manager such as nvm (macOS/Linux) or nvm-windows lets you easily switch between multiple Node.js versions across projects.

Verify your installation by checking the installed versions of node and npm:

Code Snippet

node --version
npm --version

4. Understanding Package Managers 📚

A package manager installs, updates, and manages the third-party libraries (dependencies) your project relies on. Several package managers exist in the JavaScript ecosystem, each with different trade-offs around speed, disk usage, and compatibility.

Package Manager	Key Strength	Bundled With
npm	Default, universally supported	Node.js
Yarn	Workspaces, deterministic installs	Installed separately
pnpm	Disk-efficient, very fast	Installed separately
Bun	All-in-one runtime + package manager	Installed separately

5. npm 🟥

npm (Node Package Manager) is the default package manager bundled with Node.js. It's the most widely used and universally compatible option.

Common npm Commands

npm install          # Install all dependencies
npm install react    # Install a specific package
npm run dev          # Run a script defined in package.json
npm uninstall react  # Remove a package

6. Yarn 🧶

Yarn was created to address early performance and consistency issues in npm. It remains popular for its workspaces feature, useful in monorepos.

Code Snippet

npm install --global yarn
yarn install
yarn add react
yarn dev

Note

Modern npm versions have closed much of the performance gap with Yarn, but Yarn's Plug'n'Play mode still offers unique benefits for large codebases.

7. pnpm 🚀

pnpm uses a content-addressable storage system, storing a single copy of each package version on disk and linking it across projects. This results in significantly faster installs and reduced disk usage.

Code Snippet

npm install --global pnpm
pnpm install
pnpm add react
pnpm dev

Best Practice

For projects with many dependencies or monorepos, pnpm is often the fastest and most disk-efficient choice.

8. Bun 🥟

Bun is an all-in-one JavaScript runtime, bundler, test runner, and package manager, designed for speed. It can be used as a drop-in alternative for both Node.js and traditional package managers.

Code Snippet

curl -fsSL https://bun.sh/install | bash
bun install
bun add react
bun dev

Caution

While Bun is very fast, ensure your project's dependencies and framework fully support Bun's runtime before adopting it in production.

9. Installing React ⚛️

React is not installed on its own in modern workflows — it's added automatically as a dependency when scaffolding a project with a build tool like Vite or a framework like Next.js. These tools configure the compiler, dev server, and bundler needed to run JSX-based code.

Important

Manually setting up React with raw webpack or Babel configs is possible but rarely necessary — scaffolding tools handle this complexity for you.

10. Creating a React Project with Vite ⚡

Vite is a fast, modern build tool that has become the recommended way to start a plain React SPA.

Scaffold a Vite + React Project

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

Choose the react template for JavaScript, or react-ts for TypeScript.
Vite uses native ES modules during development for near-instant server start and HMR.

11. Creating a React Project with Next.js ▲

Next.js is a full-featured React framework offering routing, server-side rendering, and Server Components out of the box.

Scaffold a Next.js Project

npx create-next-app@latest my-next-app
cd my-next-app
npm run dev

During setup, the CLI will prompt you with configuration options:

Whether to use TypeScript.
Whether to use ESLint.
Whether to use Tailwind CSS.
Whether to use the src directory.
Whether to use the App Router.

Best Practice

For new projects requiring routing, SSR, or SEO, Next.js is generally the recommended starting point over a plain Vite SPA.

12. Creating a React Project with Create React App (Legacy) ⚠️

Create React App (CRA) was historically the official way to scaffold React projects. It is now considered legacy and is no longer actively maintained or recommended by the React team.

Code Snippet

npx create-react-app my-app
cd my-app
npm start

Danger

Create React App is deprecated. Use Vite or Next.js for new projects instead.

13. Understanding the Project Structure 🗂️

While exact structures vary between tools, most React projects share a common set of conventions.

my-react-app/

package.json

vite.config.js

index.html

public/

src/

favicon.ico

main.jsx

App.jsx

components/

assets/

Header.jsx

14. Essential Project Files 📄

File	Purpose
package.json	Defines project metadata, dependencies, and scripts.
package-lock.json / pnpm-lock.yaml	Locks exact dependency versions for reproducible installs.
index.html	The entry HTML file where the React app is mounted.
vite.config.js	Configures the Vite build tool and plugins.
.gitignore	Specifies files and folders excluded from version control.

15. The src Directory 📁

The src directory contains all of your application's source code — components, styles, hooks, and assets that get processed by the build tool.

main.jsx — the application's entry point, where React mounts to the DOM.
App.jsx — the root component of the application.
components/ — reusable UI components.
assets/ — images, fonts, and other static resources imported into components.

src/main.jsx

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

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

16. The public Directory 🌐

The public directory holds static assets that are copied to the build output as-is, without being processed by the bundler. This is ideal for files like favicon.ico, robots.txt, or fonts referenced by absolute path.

Note

Assets referenced in JSX and imported via import statements should go in src/assets instead, so the bundler can optimize them.

17. Configuration Files ⚙️

File	Used By	Purpose
vite.config.js	Vite	Build tool and plugin configuration.
next.config.js	Next.js	Framework-level configuration (routing, images, etc.).
tsconfig.json	TypeScript	TypeScript compiler options.
.eslintrc.json	ESLint	Linting rules and settings.
.prettierrc	Prettier	Code formatting rules.

18. Running the Development Server 🖥️

The development server compiles your code on the fly and serves it locally, typically with HMR enabled so changes appear instantly without a full page reload.

Starting the Dev Server

npm run dev

# Example output:
# ➜  Local:   http://localhost:5173/
# ➜  Network: use --host to expose

Tip

Use the --host flag with Vite to expose the dev server on your local network, useful for testing on mobile devices.

19. Building for Production 📦

When your application is ready to deploy, run the build command to generate optimized, minified static assets.

Code Snippet

npm run build

This typically outputs to a dist (Vite) or .next (Next.js) directory, containing minified JavaScript, CSS, and other optimized static assets ready for deployment.

20. Previewing the Production Build 🔍

Before deploying, it's good practice to preview the production build locally to catch issues that don't appear in development mode.

Code Snippet

npm run preview

Tip

Always test the production build, not just the dev server — some bugs (like environment variable issues) only appear after building.

21. Environment Variables 🔐

Environment variables let you configure your app differently across environments (development, staging, production) without hardcoding values.

.env

VITE_API_URL=https://api.example.com
VITE_APP_NAME=MyReactApp

Accessing Variables in Vite

const apiUrl = import.meta.env.VITE_API_URL;

Warning

Never commit .env files containing secrets to version control. Add them to .gitignore, and only prefix public variables with VITE_ or NEXT_PUBLIC_.

22. Setting Up ESLint 🧹

ESLint statically analyzes your code to catch bugs, enforce consistent style, and flag problematic patterns before they reach production.

Installing ESLint (Vite Projects)

npm install --save-dev eslint eslint-plugin-react eslint-plugin-react-hooks

Best Practice

Most scaffolding tools (Vite templates, create-next-app) offer to configure ESLint automatically during setup — enable it whenever prompted.

23. Setting Up Prettier 🎨

Prettier is an opinionated code formatter that ensures consistent formatting across your entire codebase automatically.

Installing Prettier

npm install --save-dev prettier
npx prettier --write .

Tip

Combine eslint-config-prettier with ESLint to disable conflicting formatting rules and let Prettier handle formatting exclusively.

24. Installing React Developer Tools 🔧

React Developer Tools is a browser extension that lets you inspect the React component tree, view props and state, and profile performance directly in your browser's dev tools.

Available for Chrome, Firefox, and Edge via their respective extension stores.
Adds Components and Profiler tabs to browser dev tools.

Reference

Install it from the official React documentation page on developer tools.

25. Development Workflow 🔄

🧑‍💻

Write component code in src/.

⚡

View instant changes via HMR in the dev server.

🧹

Run ESLint and Prettier to catch issues and format code.

✅

Run tests to verify behavior.

📦

Build the app with npm run build.

🔍

Preview the production build locally.

🚀

Deploy to a hosting provider.

26. Updating Dependencies ⬆️

Checking and Updating Dependencies

npm outdated          # List outdated packages
npm update             # Update within semver ranges
npx npm-check-updates   # Check for major version updates
npx npm-check-updates -u && npm install

Caution

Major version updates can introduce breaking changes. Always review changelogs and test thoroughly after updating dependencies.

27. Common Installation Issues ⚠️

Issue	Likely Cause	Solution
EACCES permission errors	Global npm install without proper permissions	Use a version manager like nvm instead of sudo
ERESOLVE dependency conflicts	Incompatible peer dependencies	Use npm install --legacy-peer-deps or resolve manually
Port already in use	Another process using the default dev server port	Stop the process or run with a different --port
Blank page after build	Incorrect base path or routing configuration	Check base in vite.config.js

28. Troubleshooting 🩺

Delete node_modules and the lockfile, then reinstall dependencies from scratch.
Clear the package manager cache (e.g., npm cache clean --force).
Confirm your Node.js version matches the project's requirements.
Check the terminal and browser console for specific error messages.
Search the exact error message alongside your framework name for known issues.

Hint

When in doubt, a clean reinstall (rm -rf node_modules package-lock.json && npm install) resolves a surprising number of installation issues.

29. Best Practices ✅

Use a Node.js version manager to keep environments consistent across projects.
Commit your lockfile (package-lock.json, pnpm-lock.yaml) to ensure reproducible installs.
Stick to one package manager per project to avoid lockfile conflicts.
Configure ESLint and Prettier early to maintain code quality from the start.
Keep .env files out of version control using .gitignore.
Regularly update dependencies, but review changelogs for breaking changes.

30. Summary 📝

Setting up a React project involves installing Node.js, choosing a package manager, and scaffolding your project using a modern tool like Vite or Next.js. Understanding the resulting project structure, configuration files, and development workflow — along with tools like ESLint, Prettier, and React Developer Tools — lays a solid foundation for building maintainable, production-ready applications.

Summary

With your environment properly configured, you're now ready to start building your first React components and exploring core concepts like JSX, props, and state.

1. Introduction 👋

ℹ️Information

2. System Requirements 💻

3. Installing Node.js 📦

Code Snippet

Code Snippet

Code Snippet

💡Tip

Code Snippet

4. Understanding Package Managers 📚

5. npm 🟥

Common npm Commands

6. Yarn 🧶

Code Snippet

📝Note

7. pnpm 🚀

Code Snippet

⭐Best Practice

8. Bun 🥟

Code Snippet

🟡Caution

9. Installing React ⚛️

❗Important

10. Creating a React Project with Vite ⚡

Scaffold a Vite + React Project

11. Creating a React Project with Next.js ▲

Scaffold a Next.js Project

⭐Best Practice

12. Creating a React Project with Create React App (Legacy) ⚠️

Code Snippet

🚫Danger

13. Understanding the Project Structure 🗂️

14. Essential Project Files 📄

15. The src Directory 📁

src/main.jsx

16. The public Directory 🌐

📝Note

17. Configuration Files ⚙️

18. Running the Development Server 🖥️

Starting the Dev Server

💡Tip

19. Building for Production 📦

Code Snippet

20. Previewing the Production Build 🔍

Code Snippet

💡Tip

21. Environment Variables 🔐

.env

Accessing Variables in Vite

⚠️Warning

22. Setting Up ESLint 🧹

Installing ESLint (Vite Projects)

⭐Best Practice

23. Setting Up Prettier 🎨

Installing Prettier

💡Tip

24. Installing React Developer Tools 🔧

🔗Reference

25. Development Workflow 🔄

26. Updating Dependencies ⬆️

Checking and Updating Dependencies

🟡Caution

27. Common Installation Issues ⚠️

28. Troubleshooting 🩺

🔍Hint

29. Best Practices ✅

30. Summary 📝

📋Summary

Information

Tip

Note

Best Practice

Caution

Important

Best Practice

Danger

Note

Tip

Tip

Warning

Best Practice

Tip

Reference

Caution

Hint

Summary