By the end of this lesson, the default Reflex app will be running in your browser, and you'll be able to explain in one sentence how Reflex turns Python code into a web app.

1-1. What is Reflex? (10 min)

A web app usually has two parts:

• Frontend: the UI that runs in the browser, usually built with HTML, CSS and JavaScript (React and friends).
• Backend: the logic and data that run on the server, built with Python (Django, FastAPI) or similar.

Normally you have to learn both languages and design an API between them. Reflex is a full-stack framework that lets you write both the frontend and the backend in Python.

It works in three steps:

1. Compile: the Python functions that build your UI (components) run once when the app starts and are turned into React code. The output goes into the .web/ folder.
2. State lives on the server: your data (State) and event handlers run as Python on the server.
3. Sync over WebSocket: when you click a button, the browser sends an event to the server, the server sends back only the state that changed, and the page re-renders automatically.

The single Python file on the left splits two ways. The UI functions are compiled to React and shipped to the browser, while State stays on the server and syncs with the page through the ② → ③ round trip.

1-2. Set up your environment (10 min)

Install uv: uv is a tool that manages Python versions, virtual environments and packages in one place.

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Check Node.js: Reflex uses Node.js or Bun to install and run the frontend (React) packages. Reflex 0.10 requires Node 22.22.0 or later.

node -v   # should be v22.22.0 or later

1-3. Create and run a project (10 min)

uv init tutorial_261019        # create a Python project
cd tutorial_261019
uv add reflex                  # install reflex (recorded in pyproject.toml)
uv run reflex init             # scaffold a Reflex app (pick a template)
uv run reflex run              # start the dev server

• uv run runs a command inside the project's virtual environment (.venv). You don't need to activate the environment yourself.
• reflex init asks you to pick a template. To start from an empty app, you can pass it directly: uv run reflex init --template blank.
• Once reflex run is up, open the App running at: http://localhost:3000 address from the log in your browser. If port 3000 is taken, it moves to 3001 or another port.
• By default, the frontend runs on port 3000 and the backend on port 8000.
• The first run can take 1–3 minutes while it downloads the frontend packages. You need an internet connection.
• To stop the server, press Ctrl + C in the terminal.

Check your browser — Right after creating the app with --template blank, opening http://localhost:3000 should show this screen. The sun icon in the top-right corner toggles dark mode.

1-4. Two common errors on Windows (5 min)

We actually ran into these while preparing the course. Your students are likely to hit them too, so warn them up front.

• Environment variables set with setx only apply to terminals you open afterwards. If you use the VS Code terminal, restart VS Code too.
• If winget says it can't find an installed package, run winget list --name Node to check the actual package ID.

Checkpoint

• node -v shows 22.22.0 or later.
• After uv run reflex run, you can see the default page in your browser.
• You can explain in your own words: "UI functions are compiled once; event handlers run on the server every time."