Al terminar esta lección tendrás la app básica de Reflex funcionando en el navegador y podrás explicar en una frase cómo convierte Reflex tu código Python en una aplicación web.

1-1. ¿Qué es Reflex? (10 min)

Una aplicación web suele dividirse en dos partes:

• Frontend: la interfaz que se ejecuta en el navegador. Normalmente se hace con HTML, CSS y JavaScript (React, por ejemplo).
• Backend: la lógica y los datos que se ejecutan en el servidor. Se hace con Python (Django, FastAPI), entre otros.

Lo habitual es tener que aprender ambos lenguajes y, además, diseñar una API entre los dos. Reflex es un framework full stack que te permite escribir tanto el frontend como el backend en Python.

Funciona en tres pasos:

1. Compilación: al arrancar la app, las funciones de Python que construyen la pantalla (los componentes) se ejecutan una sola vez y se convierten en código React. El resultado se guarda en la carpeta .web/.
2. El estado vive en el servidor: los datos (State) y las funciones que gestionan los eventos se ejecutan en Python, en el servidor.
3. Sincronización por WebSocket: al pulsar un botón, el navegador envía un evento al servidor, el servidor devuelve solo el estado que ha cambiado y la pantalla se vuelve a dibujar automáticamente.

El único archivo Python de la izquierda se divide en dos caminos. Las funciones de pantalla se compilan a React y van al navegador; el State se queda en el servidor y se sincroniza con la pantalla mediante el ida y vuelta ②→③.

1-2. Preparar el entorno de desarrollo (10 min)

Instalar uv: uv es una herramienta que gestiona a la vez la versión de Python, el entorno virtual y los paquetes.

# 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

Comprobar Node.js: Reflex usa Node.js o Bun para instalar y ejecutar los paquetes de la parte visual (React). Reflex 0.10 requiere Node 22.22.0 o superior.

node -v   # debe ser v22.22.0 o superior

1-3. Crear y ejecutar el proyecto (10 min)

uv init tutorial_261019        # crea un proyecto de Python
cd tutorial_261019
uv add reflex                  # instala reflex (queda registrado en pyproject.toml)
uv run reflex init             # genera el esqueleto de la app Reflex (elige una plantilla)
uv run reflex run              # arranca el servidor de desarrollo

• uv run ejecuta el comando dentro del entorno virtual del proyecto (.venv). No hace falta activar el entorno virtual por separado.
• reflex init te pide que elijas una plantilla. Si quieres empezar con una app vacía, también puedes indicarla directamente: uv run reflex init --template blank.
• Cuando reflex run termine de arrancar, abre en el navegador la dirección que aparece en el log, App running at: http://localhost:3000. Si el puerto 3000 está ocupado, se usará otro, como el 3001.
• Por defecto, el frontend se ejecuta en el puerto 3000 y el backend en el 8000.
• La primera ejecución puede tardar entre 1 y 3 minutos porque descarga los paquetes de la interfaz. Necesitas conexión a internet.
• Para detener el servidor, pulsa Ctrl + C en la terminal.

Compruébalo en el navegador — Justo después de crear el proyecto con --template blank, al abrir http://localhost:3000 deberías ver esta pantalla. El icono del sol, arriba a la derecha, es el botón para cambiar al modo oscuro.

1-4. Dos errores frecuentes en Windows (5 min)

Son problemas que encontramos de verdad al preparar el curso. Es muy probable que a tus alumnos les pase lo mismo, así que avísales con antelación.

• Las variables de entorno definidas con setx solo se aplican a partir de las terminales que abras después. Si usas la terminal de VS Code, reinicia también VS Code.
• Si winget responde que no encuentra ningún paquete instalado, comprueba el ID real del paquete con winget list --name Node.

Punto de control

• node -v muestra 22.22.0 o superior.
• Tras uv run reflex run, ves la pantalla básica en el navegador.
• Puedes explicar con tus propias palabras que "las funciones de pantalla se compilan una vez y las funciones de eventos se ejecutan en el servidor cada vez".