# React + Vite Setup

The browser playground (react.new) is perfect for learning React. When you want to build a real project, you run React on your own machine. This guide walks you through it.

You only need this when you are ready to build a full React app. For practicing concepts, the in-browser playground is enough.

## What You Are Installing and Why

- **Node.js**: a program that runs JavaScript outside the browser. The React build tools are JavaScript, so they need Node to run. Installing Node also gives you `npm`, the package installer.
- **Vite**: a build tool. It creates the project folder, translates JSX into browser-ready JavaScript, and runs a live local server that refreshes the moment you save.

## 1. Install Node.js

1. Go to [nodejs.org](https://nodejs.org)
2. Download the **LTS** version (the one labeled "Recommended for Most Users")
3. Run the installer and accept the defaults
4. Restart VS Code so it picks up the new install

Check that it worked. Open a terminal and run:

```bash
node --version
npm --version
```

Both should print a version number. If you get "command not found," restart your computer and try again.

## 2. Create a New React Project

In the terminal, navigate to the folder where you keep your projects, then run:

```bash
npm create vite@latest
```

Vite will ask you a few questions:

1. **Project name:** type a name, for example `my-react-app`
2. **Select a framework:** use the arrow keys to choose **React**
3. **Select a variant:** choose **JavaScript** (not TypeScript, for now)

## 3. Install Dependencies and Run

Vite prints three commands at the end. Run them one at a time:

```bash
cd my-react-app
npm install
npm run dev
```

- `cd` moves into your new project folder
- `npm install` downloads the libraries the project needs (this creates the `node_modules` folder)
- `npm run dev` starts the local dev server

You will see a line like:

```text
  ➜  Local:   http://localhost:5173/
```

Open that URL in your browser. You should see the Vite + React starter page. Edit `src/App.jsx`, save, and the page updates on its own.

To stop the server, click the terminal and press `Ctrl+C`.

## 4. What Is in the Project

```text
my-react-app/
├── index.html        the single HTML page React mounts into
├── package.json      lists dependencies and scripts (npm run dev, etc.)
├── node_modules/     installed libraries (never edit, never commit)
└── src/
    ├── main.jsx      starts React and inserts App into the page
    ├── App.jsx       the root component, a good place to start
    └── App.css       styles for App
```

Start by editing `src/App.jsx`. Build your own components in new files under `src/` and import them into `App`.

## 5. Deploying a Vite Project

A Vite project is **not** ready to deploy the way a plain HTML site is. The `src/` files use JSX, which browsers cannot read directly. You first build a plain-HTML version:

```bash
npm run build
```

This creates a `dist/` folder with plain HTML, CSS, and JavaScript. That `dist/` folder is what you deploy. Deploying a Vite app to GitHub Pages takes an extra configuration step, so ask in class or check the Vite deployment docs when you get there.

## Troubleshooting

**`npm create vite@latest` does nothing or errors**
- Make sure Node installed correctly: `node --version` should print a number
- Restart VS Code (or your computer) after installing Node

**`npm run dev` fails with "command not found" or a missing module**
- Make sure you ran `npm install` first, inside the project folder
- Make sure you are in the right folder: `cd my-react-app`

**The page is blank**
- Check the terminal and the browser console for red error messages
- A common cause is a typo in JSX, such as a missing closing tag

**Should I commit `node_modules`?**
- No. It is large and rebuildable. Vite projects include a `.gitignore` that excludes it. Anyone who clones your repo runs `npm install` to recreate it.

## References

- [Vite: Getting Started](https://vite.dev/guide/)
- [react.dev: Start a New React Project](https://react.dev/learn/build-a-react-app-from-scratch)
- [Node.js downloads](https://nodejs.org)