Setting up a React project

From an empty folder to React in the browser

So far you've run React inside this page. To build your own app, you need a project: a folder with your components, the packages they use, and a tool that turns them into a page a browser can open. One command makes that folder for you. When you start it, the browser shows a small counter. Here is that counter's component, cut down to the parts that run (the real file also shows three images and a few links). Click the button in the result.

1import { useState } from 'react'2 3function App() {4  const [count, setCount] = useState(0)5 6  return (7    <section id="center">8      <h1>Get started</h1>9      <p>10        Edit <code>src/App.jsx</code> and save to test <code>HMR</code>11      </p>12      <button13        type="button"14        className="counter"15        onClick={() => setCount((count) => count + 1)}16      >17        Count is {count}18      </button>19    </section>20  )21}22 23export default App

Line 1 imports useState from the react package. Lines 3 to 21 are the component, a function named App. Line 4 gives it a number to remember, count, starting at 0 (this is state; you met it in Why React?). Lines 6 to 20 describe the screen: a heading, a sentence, and a button. Line 15 runs when you click the button and asks React for the next number, so line 17 shows Count is 1, then 2. Line 23 exports App so another file can use it.

Now press Edit & run, click the button a few times, and change Get started on line 8 to Tip calculator. The result shows the new heading a moment later. On this page each change runs the example again, so the count goes back to 0. In your own project it's better: when you save App.jsx, the browser updates the heading and keeps the count. That's the HMR on line 10: hot module replacement, swapping one changed file into the running page without reloading it.

Vite or a framework

There are two kinds of tools for starting a React project, and React's own documentation, react.dev, names both. This is what its Creating a React App page says, as checked in October 2026:

• For a new app or website, start with a framework. A framework is React plus the parts a whole app needs: page addresses (which page shows for /cart), loading data, and the build. The page recommends Next.js (its App Router), React Router, and Expo for phone apps, and lists TanStack Start and RedwoodSDK as newer options.
• To learn React, or when no framework fits, build from scratch with a build tool such as Vite, Parcel, or Rsbuild. You get React and a development server, and you choose everything else yourself.

Each recommended framework starts with one command:

npx create-next-app@latest
npx create-react-router@latest
npx create-expo-app@latest

Line 1 makes a Next.js project, line 2 a React Router project, and line 3 an Expo project for phone and web apps. npx runs a package's command without installing it first, and @latest asks for its newest version. Each one asks a few questions, then makes a folder. Frameworks don't need a server of their own, either: react.dev notes they can also build a plain app that runs only in the browser.

How to read the table: each row asks the same question of a Vite project and a framework project.

This course uses Vite. It's the smallest setup that is still a real project, and you see every file, including the one that starts React. A framework hides that file and calls createRoot for you, which is handy in an app and confusing while you learn. The React frameworks lesson covers them once you know React itself.

Creating a project with Vite

You need Node.js, the program that runs JavaScript outside the browser, and npm, which comes with it (the Setting up your tools lesson installs both). Then open a terminal in the folder where you keep projects and run these four commands:

npm create vite@latest tip-calculator -- --template react
cd tip-calculator
npm install
npm run dev

1. Line 1 runs create-vite, Vite's project maker. tip-calculator is the new folder's name. The -- passes what comes after it to create-vite instead of npm, and --template react picks React with JavaScript.
2. Line 2 moves the terminal into the new folder.
3. Line 3 downloads the packages listed in package.json into a folder called node_modules (the npm & package.json lesson explains how).
4. Line 4 starts Vite's development server: a small web server on your computer that serves the project while you work.

Line 1 still asks a couple of questions in the terminal. Run npm create vite@latest with nothing after it, and it asks every question, one at a time. How to read the table: the left column is the question, the right column is what to pick for this course.

When the server is running, the terminal shows something like this:

  VITE v8.3.5  ready in 312 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Line 1 names the Vite version and how long it took to start. Line 3 is the address to open: http://localhost:5173/. localhost means "this computer", and 5173 is the port Vite picks when it's free. Line 4 says the app is only reachable from your own computer. The server keeps running until you press Ctrl + C in the terminal.

What's in a new project

Here is the new folder, after npm install:

tip-calculator/
├── node_modules/        (made by npm install)
├── public/
│   ├── favicon.svg
│   └── icons.svg
├── src/
│   ├── assets/
│   │   ├── hero.png
│   │   ├── react.svg
│   │   └── vite.svg
│   ├── App.css
│   ├── App.jsx
│   ├── index.css
│   └── main.jsx
├── .gitignore
├── .oxlintrc.json
├── index.html
├── package-lock.json    (made by npm install)
├── package.json
├── README.md
└── vite.config.js

• src is your code. App.jsx is where you write the app, and main.jsx starts it. index.css styles the whole page, and App.css styles the starter.
• src/assets holds images your code imports. public holds files served as they are, at the top of the site: public/favicon.svg is the tab icon, at /favicon.svg.
• .gitignore lists what Git, the version-control tool, should skip, like node_modules. .oxlintrc.json sets up Oxlint, the linter you picked.

Three files at the top hold the setup. First, package.json:

1{2  "name": "tip-calculator",3  "private": true,4  "version": "0.0.0",5  "type": "module",6  "scripts": {7    "dev": "vite",8    "build": "vite build",9    "lint": "oxlint",10    "preview": "vite preview"11  },12  "dependencies": {13    "react": "^19.3.1",14    "react-dom": "^19.3.1"15  },16  "devDependencies": {17    "@types/react": "^19.3.0",18    "@types/react-dom": "^19.3.0",19    "@vitejs/plugin-react": "^6.1.2",20    "oxlint": "^1.88.0",21    "vite": "^8.3.4"22  }23}

Line 2 is the project's name. Line 5, "type": "module", says the JavaScript files use import and export. Lines 6 to 11 are the scripts: npm run dev runs line 7, vite. Lines 12 to 15 are the packages your app runs with: react and react-dom. The ^ in ^19.3.1 means "19.3.1 or a newer 19 release". Lines 16 to 22 are tools you only need while building the app: Vite, its React plugin, Oxlint, and type information for editors.

Next, the page itself:

1<!doctype html>2<html lang="en">3  <head>4    <meta charset="UTF-8" />5    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" />7    <title>tip-calculator</title>8  </head>9  <body>10    <div id="root"></div>11    <script type="module" src="/src/main.jsx"></script>12  </body>13</html>

In a Vite project, index.html sits at the top of the folder, not in public. It's the page the browser opens. Its <body> holds only two things: line 10, an empty <div id="root">, and line 11, a <script type="module"> that loads src/main.jsx. create-vite put the project's name into the <title> on line 7.

Last, Vite's settings:

import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
})

Line 1 imports Vite's React plugin, and line 6 turns it on. The plugin sets up how your JSX becomes JavaScript, and adds Fast Refresh, the part of hot module replacement that keeps a component's state when you save its file. You'll rarely change this file. The Bundlers & build tools lesson shows what Vite does with your files.

Use the playground to go through the files in the order things happen: npm reads package.json, the browser opens index.html, which loads main.jsx, which imports App.jsx. Each button shows the real file, what reads it, and how often you'll edit it.

{
  "name": "tip-calculator",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "oxlint",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1"
  },
  "devDependencies": {
    "@types/react": "^19.3.0",
    "@types/react-dom": "^19.3.0",
    "@vitejs/plugin-react": "^6.1.2",
    "oxlint": "^1.88.0",
    "vite": "^8.3.4"
  }
}

createRoot and StrictMode: where React starts

Why React? showed this file briefly, and How React works: a first look mentioned StrictMode's second call. Here is the file as the template makes it, src/main.jsx:

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

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

1. Line 1 imports StrictMode from react, the package every React app shares.
2. Line 2 imports createRoot from react-dom/client, the part of React that draws to a web page in the browser.
3. Line 3 imports a CSS file. That isn't JavaScript: Vite sees the import and adds the styles to the page.
4. Line 4 imports your App component from App.jsx.
5. Line 6 finds the empty <div id="root"> from index.html and gives it to createRoot, which makes a root: React takes over everything inside that element. Then .render(…) tells React what to show there.
6. Lines 7 to 9 are what it shows: <App />, wrapped in <StrictMode>.

Most apps have exactly one createRoot call, and you write it once and leave it. The first time render runs, React clears anything already inside the element. From then on, you never touch the page yourself: your components describe it.

Here is the same file, live. The preview on this page links CSS files from the page instead, so this copy leaves out line 3. Its App.jsx tab holds a component that prints a line to the console each time React calls it:

1import { StrictMode } from 'react'2import { createRoot } from 'react-dom/client'3import App from './App.jsx'4 5createRoot(document.getElementById('root')).render(6  <StrictMode>7    <App />8  </StrictMode>,9)

The result shows the heading, and the console under it shows Rendering App with a small 2 beside it: the line was printed twice. That's StrictMode. In development, it makes React call each component a second time, to catch components that do something they shouldn't while being called. A component that only works out what to show gives the same answer both times, so you see no difference on the page.

Press Edit & run and try two changes, one at a time, pressing Reset in between:

• Delete line 6 and line 8, so line 7 is just <App />. The console shows Rendering App once, with no 2.
• Change 'root' on line 5 to 'app'. The page has no element with that id, so getElementById gives null, and the result shows React's error: Target container is not a DOM element.

StrictMode's checks, as react.dev lists them, all in development only:

• React calls your components an extra time, to find rendering that isn't pure.
• React runs Effects an extra time, to find Effects that don't clean up after themselves.
• React runs ref callbacks an extra time, to find refs that don't clean up.
• React warns when your code uses old APIs that are going away.

Effects and refs come later in the course; for now, remember that StrictMode only adds checks, and the production build made by npm run build leaves them all out. Keep it: react.dev recommends wrapping the whole app in it. You'll learn what "pure" means, and why the double call finds bugs, in Keeping components pure.

export function createRoot(
  container: Element | Document | DocumentFragment,
  options?: CreateRootOptions,
): RootType {
  if (!isValidContainer(container)) {
    throw new Error('Target container is not a DOM element.');
  }

React's code adds type notes, like : Element, which you can read past. Lines 5 to 7 are the check: when container isn't an element, such as the null from a wrong id, line 6 throws the error you saw.

Seeing your components with React DevTools

The browser's developer tools show the page's elements: <div>, <button>, and so on (the Debugging in the browser lesson tours them). They don't show your components. React DevTools does. It's a free browser extension, made by the React team, for Chrome, Firefox, and Edge. Install it once, and it works on every React page you open.

Then open a React page, like your project at localhost:5173, and open the developer tools. Two new tabs appear: Components and Profiler. To try them, put this in your project's App.jsx. Here it runs live, so you can see what it does first:

1import { useState } from 'react'2 3function ProductCard({ name, price, onAdd }) {4  return (5    <p>6      {name}: ${price} <button onClick={onAdd}>Add</button>7    </p>8  )9}10 11export default function App() {12  const [count, setCount] = useState(0)13 14  return (15    <>16      <h2>In cart: {count}</h2>17      <ProductCard name="Tea" price={3} onAdd={() => setCount(count + 1)} />18      <ProductCard name="Cake" price={4} onAdd={() => setCount(count + 1)} />19    </>20  )21}

Lines 3 to 9 are a ProductCard component that shows a name, a price, and an Add button. Lines 11 to 21 are App: line 12 keeps a count in state, line 16 shows it, and lines 17 and 18 use ProductCard twice, with different props. Click Add on either card and the count goes up.

In the Components tab, the tree shows App and its two ProductCard components. Select the second card: the panel beside the tree shows its props, name: "Cake" and price: 4. Select App, and under hooks it shows its state, State: 0. Click Add on the page twice and the panel says State: 2. You can also change a value in the panel, and the page follows.

How to read the table: each row is one part of React DevTools, what it shows, and when you'd use it.

For Safari and other browsers without the extension, react.dev gives a separate app. Install it, start it, and it prints a <script> tag to add to the top of your page's <head>:

npm install -g react-devtools
react-devtools

Line 1 installs the react-devtools package for your whole computer (-g), not into one project. Line 2 opens its window. React DevTools also makes StrictMode's second call easier to read: react.dev notes that, with it installed, logs from the second call appear slightly dimmed in the console.

Your first changes to a new project

The starter is there to prove everything works. Once you've seen the counter, make the project yours. In the next lesson you'll build a tip calculator, and it starts like this:

1. Replace everything in src/App.jsx with your own component.
2. Delete src/App.css and the images in src/assets if nothing imports them. Empty src/index.css, or keep it for styles the whole page shares.
3. Leave main.jsx, index.html, and vite.config.js as they are.

1export default function App() {2  return (3    <main>4      <h1>Tip calculator</h1>5      <p>Work out the tip and split the bill.</p>6    </main>7  )8}

Line 1 exports the component as the file's default, the one main.jsx imports, in a shorter way than the starter: on the same line as the function. Lines 3 to 6 describe a <main> with a heading and one sentence. The styles.css tab stands in for index.css: this page links it for you, where your project imports it in main.jsx.

Each script in package.json has its moment. How to read the table: the first column is what you type, then what it does, then when you use it.

Every tool in the project has its own job, and knowing which does what helps when something goes wrong. Sort each job:

Common mix-ups

• "Start with Create React App." No. It was deprecated in February 2025. Start with a framework, or with Vite to learn.
• "Vite is a React framework." No. It's a build tool: a development server and a build. It works with Vue, Svelte, plain JavaScript, and more. It doesn't add page addresses or server rendering.
• "StrictMode calls my components twice for my users too." No. The extra calls happen only in development. The production build calls each component once.
• "StrictMode changes what my app shows." No. It only adds checks. If the page looks different with it, a component is doing something while rendering that it shouldn't.
• "React makes the root element." No. index.html has it, and main.jsx must find it by the same id. A wrong id gives null, and createRoot throws.
• "React DevTools is a package in my project." No. It's a browser extension. The react-devtools npm package is a separate app, for browsers without the extension.
• "The browser runs my JSX files." No. Browsers can't read JSX. Vite turns each file into plain JavaScript before the browser gets it.

Practice exercises

Most exercises show their result under the code. Press Edit & run to change the code and watch the result, and its console, update.

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

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

1import { StrictMode } from 'react'2import { createRoot } from 'react-dom/client'3import App from './App.jsx'4 5createRoot(document.getElementById('root')).render(6  <StrictMode>7    <App />8  </StrictMode>,9)

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

createRoot(document.getElementById('app')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

1import { StrictMode } from 'react'2import { createRoot } from 'react-dom/client'3import App from './App.jsx'4 5createRoot(document.getElementById('root')).render(6  <StrictMode>7    <App />8  </StrictMode>,9)

1import { useState } from 'react'2 3function App() {4  const [count, setCount] = useState(0)5 6  return (7    <section id="center">8      <h1>Get started</h1>9      <p>10        Edit <code>src/App.jsx</code> and save to test <code>HMR</code>11      </p>12      <button13        type="button"14        className="counter"15        onClick={() => setCount((count) => count + 1)}16      >17        Count is {count}18      </button>19    </section>20  )21}22 23export default App

1import { useState } from 'react'2 3function App() {4  const [count, setCount] = useState(0)5 6  return (7    <section id="center">8      <h1>Get started</h1>9      <p>10        Edit <code>src/App.jsx</code> and save to test <code>HMR</code>11      </p>12      <button13        type="button"14        className="counter"15        onClick={() => setCount((count) => count + 1)}16      >17        Count is {count}18      </button>19      <button type="button" onClick={() => setCount(0)}>20        Reset21      </button>22    </section>23  )24}25 26export default App

{
  "name": "tip-calculator",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "oxlint",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1"
  },
  "devDependencies": {
    "@types/react": "^19.3.0",
    "@types/react-dom": "^19.3.0",
    "@vitejs/plugin-react": "^6.1.2",
    "oxlint": "^1.88.0",
    "vite": "^8.3.4"
  }
}

{
  "name": "tip-calculator",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "oxlint",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1"
  },
  "devDependencies": {
    "@types/react": "^19.3.0",
    "@types/react-dom": "^19.3.0",
    "@vitejs/plugin-react": "^6.1.2",
    "oxlint": "^1.88.0",
    "vite": "^8.3.4"
  }
}

1import { StrictMode } from 'react'2import { createRoot } from 'react-dom/client'3import CartBadge from './CartBadge.jsx'4import Reviews from './Reviews.jsx'5 6createRoot(document.getElementById('cart-badge')).render(7  <StrictMode>8    <CartBadge />9  </StrictMode>,10)

1import { StrictMode } from 'react'2import { createRoot } from 'react-dom/client'3import CartBadge from './CartBadge.jsx'4import Reviews from './Reviews.jsx'5 6createRoot(document.getElementById('cart-badge')).render(7  <StrictMode>8    <CartBadge />9  </StrictMode>,10)11 12createRoot(document.getElementById('reviews')).render(13  <StrictMode>14    <Reviews />15  </StrictMode>,16)

1const orders = []2 3export default function OrderCount() {4  orders.push('Tea')5  return <p>Orders: {orders.length}</p>6}

1export default function OrderCount() {2  const orders = ['Tea']3  return <p>Orders: {orders.length}</p>4}

Check your understanding

For each question, think about which file or tool is doing the work. Press Edit & run on a question's code to check.

Key takeaways

• React's documentation recommends a framework, like Next.js or React Router, for a new app, and a build tool like Vite to learn React or when no framework fits.
• npm create vite@latest tip-calculator -- --template react makes a project; npm install gets its packages; npm run dev serves it at localhost:5173 and updates the page as you save.
• The browser opens index.html, which loads src/main.jsx, which imports App from src/App.jsx.
• createRoot takes over one element, usually <div id="root">, and render shows your app inside it.
• StrictMode calls your components twice and adds other checks, only in development, to find mistakes early. It changes nothing for your users.
• React DevTools is a browser extension that shows your component tree, with each component's props and state.

Coming next: Your first React app. You'll build a small tip calculator in this project, one step at a time: components, data, a click, and state.