Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 132 ยท Getting Started

Setting Up a React Project

Learn how to start a real React project. Compare Vite, Next.js, React Router and Expo, tour the folder layout, scripts, ESLint hooks rules and DevTools.

Everything in this tutorial runs in the editor on the page, so you do not have to install anything to learn React. Sooner or later, though, you will want a real project on your own computer: a place where you can split code into files, install packages, see changes instantly while you type and build a fast version for visitors.

This lesson is a guided tour of that world. The commands here are read-only: they need Node.js, a terminal and a package manager, which our browser editor does not have, so copy them to your own machine when you are ready. You will learn which starting point to choose, what the files in a new project do, which tools catch mistakes for you, and how our in-browser editor fakes all of this with a single module.

You need a build step

Browsers cannot run JSX, and a real app is made of many files and many npm packages. So a React project uses a build tool that does a few jobs:

  • Compile JSX (and TypeScript) into plain JavaScript.
  • Bundle your files and the packages you import into a few optimized files.
  • Serve a development server with hot module replacement: when you save a file, the browser updates without losing the state of the page.
  • Optimize for production: remove unused code, minify, split code into chunks and add content hashes to file names so browsers can cache them.

You rarely configure this by hand. You pick a starting point that has made good choices for you.

Choosing a starting point

React's own documentation recommends starting from a framework for most new apps, or from a build tool if you want a single-page app with full control. In practice these are the main options:

Option What it is Good for
Vite A fast build tool with a React template; you add a router and the rest yourself Learning, single-page apps, dashboards, libraries, internal tools
Next.js A full-stack React framework: file-based routing, server rendering, server components, API routes Websites and apps that need SEO, fast first load, a server in the same project
React Router (framework mode) The popular router grown into a framework (it absorbed Remix): loaders, actions, server rendering Apps built around routes, forms and data loading
Expo The recommended framework for React Native Mobile apps for iOS and Android (and web) from one codebase

A short decision guide:

  1. Learning React, or building a client-only app? Vite.
  2. A public website where search engines and first-load speed matter, or an app with its own backend? Next.js or React Router framework mode.
  3. A phone app? Expo.

Older tutorials tell you to use Create React App. It is no longer maintained and should not be used for new projects. If you find it in a codebase, treat it as a candidate for migration to Vite or a framework.

Starting a Vite project

This is read-only; run it on your own machine with a current Node.js LTS installed.

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

The last command starts the development server and prints a local address such as http://localhost:5173. Open it, edit src/App.jsx, save, and watch the page update. Use --template react-ts if you want TypeScript (see the TypeScript with React chapter later in this tutorial).

Starting a framework project

Terminal
# Next.js
npx create-next-app@latest my-site

# React Router framework mode
npx create-react-router@latest my-app

# Expo (React Native)
npx create-expo-app@latest my-phone-app

Each command asks a few questions (TypeScript, styling, router style) and generates a ready-to-run project. Frameworks add conventions on top of React, such as where pages live and how data is loaded on the server. The React you write inside a component is the same React you learn here.

What the choice changes (and what it does not)

Everything in the chapters on components, props, state, events, hooks and forms is identical in all four. What differs is around your components: how URLs map to pages, where data is fetched, and whether components can run on the server. We cover routing in the Routing and Apps chapter and server components later in the tutorial.

A tour of the folder layout

A fresh Vite React project looks roughly like this:

TEXT
my-app/
  index.html          the one HTML page; contains <div id="root"></div>
  package.json        name, scripts and dependencies
  vite.config.js      build tool settings
  eslint.config.js    lint rules
  public/             files served as-is (favicon, robots.txt)
  src/
    main.jsx          entry point: creates the root and renders <App />
    App.jsx           your top-level component
    App.css
    components/       (you create this) reusable UI pieces

The important file is the entry point. It is exactly the code you have been writing at the bottom of every example, just wrapped in two extras:

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

index.html has the empty <div id="root"></div> and a <script type="module" src="/src/main.jsx"> tag. The dev server turns that script (and everything it imports) into JavaScript on the fly.

The folder structure grows with you

There is no official layout. Common habits that work well:

  • Start flat. Keep src/ simple until it hurts. Ten components in one folder is fine.
  • Group by feature once it grows: src/features/cart/ holding the cart components, hooks and helpers together, instead of one giant components/ folder.
  • Name component files after the component, in PascalCase: ProductCard.jsx exports ProductCard.
  • Put shared helpers in src/lib/ or src/utils/, and custom hooks in files starting with use.

Designing Components returns to this once you have written more code.

The scripts in package.json

The generated package.json has a scripts section. The names are conventions, and the Vite ones are:

JSON
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint ."
  }
}
  • npm run dev starts the development server with hot reload and extra checks.
  • npm run build compiles and optimizes the production bundle into a dist/ folder, which any static host can serve.
  • npm run preview serves that built folder locally so you can test the real output.
  • npm run lint runs ESLint over the code.

Frameworks use the same names (dev, build, start) with more features behind them.

Mistake detectors: ESLint and StrictMode

Two tools catch a surprising number of React bugs before users do.

ESLint and the hooks plugin

ESLint is a linter: it reads your code and reports suspicious patterns. The Vite template installs it together with eslint-plugin-react-hooks, which provides the two rules every React developer should keep switched on:

  • rules-of-hooks reports hooks called conditionally, inside loops or outside components and custom hooks. The reasons are in The Rules of Hooks.
  • exhaustive-deps reports effects (and useMemo/useCallback) whose dependency list does not match the values they use. This prevents a whole family of stale-value bugs; see Effect Dependencies.

Treat their messages as bugs, not style suggestions. Silencing them with a comment is almost always a sign that the code needs a different design.

StrictMode

Notice <StrictMode> in the entry file above. In development it re-renders components an extra time and runs each effect's setup and cleanup an extra time, to surface impure renders and missing cleanup. It does nothing in production builds. It is a mistake detector, not a bug: if something runs twice in development, find out why before you try to remove StrictMode.

Our browser editor loads React's development build, so StrictMode's extra checks run here too. Run this and look at the console: you will see render twice, then effect setup, effect cleanup and effect setup again.

StrictMode in the editor

A Vite or Next.js dev server prints the same sequence, while a production build runs each only once. The lessons on Keeping Components Pure and Cleanup, Subscriptions and Timers explain why that is valuable.

React DevTools

React Developer Tools is a free browser extension for Chrome, Firefox and Edge. It adds two tabs to the browser's developer tools:

  • Components shows the component tree of the page, with the props, state and hooks of each component. You can edit values live to test.
  • Profiler records interactions and shows which components rendered and how long they took. We use it in Profiling and Debugging Performance.

DevTools only fully works against development builds. It is the quickest answer to "what props did this component actually receive?" and to "why did this re-render?".

How our editor runs React

Every jsx example on this site is a single module. When you press Run (or edit with Live mode on), the page builds a small document inside a sandboxed iframe:

  1. an empty <div id="root"></div>,
  2. an import map that says where react, react-dom/client and friends come from (a CDN, pinned to React 19.3.1),
  3. an in-browser Babel compiler configured for JSX,
  4. your code as a module.

You can look at the import map from inside the example:

The import map behind the editor

That is the whole toolbox: React and React DOM. There is no npm, no node_modules, no bundler. Therefore:

  • You cannot import third-party packages such as a router or a state library. When a lesson needs one, it shows the real code read-only and then builds a small working stand-in by hand.
  • Everything is one file. In a project you would split Badge and App into Badge.jsx and App.jsx and use import Badge from './Badge.jsx'; here they sit in one file so each example is complete.
  • The preview is sandboxed: no localStorage, cookies or real history.pushState.

Because there is no bundler, build-time features are missing too. For example import.meta.env, the way Vite exposes environment variables, is undefined here:

Build-time features do not exist here

In a Vite project import.meta.env.MODE would be "development" or "production", and environment variables you name with the VITE_ prefix would appear on import.meta.env. (Never put secrets in client-side variables: anything in the bundle is visible to every visitor.)

Publishing a component to npm

Once a component is useful in more than one project, you can package it. The steps are the same for any library; the React-specific parts are the peer dependencies and the build output. (This section is read-only: the editor cannot publish packages.)

  1. Create the package. A folder with src/Button.jsx, a src/index.js that re-exports your components, and a package.json.
  2. Declare React as a peer dependency, not a normal dependency, so the app and your library share a single copy of React. Two copies break hooks.
  3. Build to plain JavaScript. Browsers and Node cannot read JSX, so a bundler such as Vite (library mode) or tsup compiles src into dist, in ES module format, plus type declarations if you use TypeScript.
  4. Point package.json at the output and publish only dist.
JSON
{
  "name": "@yourname/fancy-button",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "exports": { ".": "./dist/index.js" },
  "files": ["dist"],
  "peerDependencies": { "react": ">=18", "react-dom": ">=18" },
  "scripts": { "build": "vite build" }
}
Terminal
npm run build           # compile JSX into dist/
npm pack --dry-run      # list exactly which files would be published
npm login               # once per machine
npm publish --access public

Follow semantic versioning: bump the patch version for fixes, the minor version for new features and the major version for breaking changes (npm version minor does the bump and creates a git tag). Test the package locally before publishing: run npm pack and install the resulting tarball into a real app.

Choosing for yourself: a small picker

To finish, here is a tiny component that remembers the kind of project you want and prints the matching command. Pick an option; it is plain state and rendering, the same ideas as in the introduction.

Which starter should I use?

If you are unsure, pick Vite for learning and a framework when you have a real product with real SEO or server needs. Moving later is possible because your components stay the same.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does a real React project need a build tool?

    JSX must be compiled to JavaScript, and a real app has many files and packages that are bundled and optimized. Build tools also provide a dev server with hot reload.
  2. 2. Which starting point is the natural choice for a React Native phone app?

    Expo is the recommended framework for React Native. Vite and Next.js target the web, and Create React App is no longer maintained.
  3. 3. What does the exhaustive-deps lint rule check?

    exhaustive-deps compares the values read inside an effect (or useMemo/useCallback) with its dependency array. rules-of-hooks is the rule that checks where hooks may be called.
  4. 4. What does a StrictMode-wrapped component log in our in-browser editor: render, effect setup?

    StrictMode renders twice and runs setup, cleanup, setup in development builds, which is what the editor loads. A production build does each only once.
  5. 5. In a Vite project, what is the job of npm run build?

    dev starts the dev server, lint runs ESLint and install fetches packages. build produces optimized static files in dist/.

Summary

  • Real projects need a build step for JSX, bundling, a dev server and production optimization; you pick a starter instead of configuring it.
  • Vite is the simple choice for learning and single-page apps; Next.js and React Router framework mode add routing and server rendering; Expo is for mobile.
  • A project has index.html with the root element, src/main.jsx as the entry point, src/App.jsx for your top component and scripts such as dev, build, preview and lint.
  • Keep eslint-plugin-react-hooks on (rules-of-hooks, exhaustive-deps) and use StrictMode in development to catch bugs early.
  • React DevTools shows the component tree, props, state and render timings.
  • Our editor runs one module with an import map and in-browser Babel on React 19.3.1; packages, files and build-time features are shown read-only.

Next: JSX Basics