이번 교시가 끝나면 브라우저에서 Reflex 기본 앱이 뜨고, Reflex가 파이썬 코드를 어떻게 웹앱으로 바꾸는지 한 문장으로 설명할 수 있습니다.

1-1. Reflex는 무엇인가 (10분)

웹앱은 보통 두 부분으로 나뉩니다.

• 프론트엔드: 브라우저에서 도는 화면. 보통 HTML, CSS, JavaScript(React 등)로 만듭니다.
• 백엔드: 서버에서 도는 로직과 데이터. 파이썬(Django, FastAPI) 등으로 만듭니다.

보통은 두 언어를 모두 배워야 하고, 둘 사이에 API를 설계해야 합니다. Reflex는 프론트엔드와 백엔드를 모두 파이썬으로 쓰게 해 주는 풀스택 프레임워크입니다.

동작 원리는 세 단계입니다.

1. 컴파일: 화면을 만드는 파이썬 함수(컴포넌트)를 앱 시작 때 한 번 실행해 React 코드로 바꿉니다. 결과물은 .web/ 폴더에 쌓입니다.
2. 상태는 서버에: 데이터(State)와 이벤트 처리 함수는 서버의 파이썬에서 실행됩니다.
3. WebSocket으로 동기화: 버튼을 누르면 브라우저가 서버에 이벤트를 보내고, 서버는 바뀐 상태만 돌려보내며, 화면이 자동으로 다시 그려집니다.

왼쪽의 파이썬 파일 하나가 두 갈래로 나뉩니다. 화면 함수는 React로 컴파일되어 브라우저로 가고, State는 서버에 남아 ②→③ 왕복으로 화면과 동기화됩니다.

1-2. 개발 환경 준비 (10분)

uv 설치: uv는 파이썬 버전, 가상환경, 패키지를 한 번에 관리하는 도구입니다.

# 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

Node.js 확인: Reflex는 화면 쪽(React) 패키지를 설치·실행하는 데 Node.js나 Bun을 씁니다. Reflex 0.10은 Node 22.22.0 이상을 요구합니다.

node -v   # v22.22.0 이상이어야 함

1-3. 프로젝트 만들고 실행하기 (10분)

uv init tutorial_261019        # 파이썬 프로젝트 생성
cd tutorial_261019
uv add reflex                  # reflex 설치 (pyproject.toml에 기록됨)
uv run reflex init             # Reflex 앱 뼈대 생성 (템플릿 선택)
uv run reflex run              # 개발 서버 실행

• uv run은 프로젝트의 가상환경(.venv) 안에서 명령을 실행합니다. 가상환경을 따로 활성화하지 않아도 됩니다.
• reflex init은 템플릿을 묻습니다. 빈 앱에서 시작하려면 uv run reflex init --template blank처럼 지정해도 됩니다.
• reflex run이 끝나면 로그의 App running at: http://localhost:3000 주소를 브라우저로 엽니다. 3000번 포트가 사용 중이면 3001번 등으로 바뀝니다.
• 프론트엔드는 3000번, 백엔드는 8000번 포트에서 도는 것이 기본입니다.
• 첫 실행은 화면용 패키지를 내려받느라 1~3분 걸릴 수 있습니다. 인터넷이 필요합니다.
• 서버를 끄려면 터미널에서 Ctrl + C를 누릅니다.

브라우저 확인 — --template blank로 만든 직후 http://localhost:3000을 열면 이 화면이 보여야 합니다. 오른쪽 위 해 아이콘은 다크모드 전환 버튼입니다.

1-4. Windows에서 자주 만나는 에러 2가지 (5분)

강의 준비 중 실제로 겪은 문제입니다. 수강생도 똑같이 겪을 가능성이 높으니 미리 안내하세요.

• setx로 설정한 환경변수는 새로 연 터미널부터 적용됩니다. VS Code 터미널이라면 VS Code도 다시 엽니다.
• winget에서 "설치된 패키지를 찾을 수 없습니다"가 나오면 winget list --name Node로 실제 패키지 ID를 확인합니다.

체크포인트

• node -v가 22.22.0 이상이다.
• uv run reflex run 후 브라우저에서 기본 화면이 보인다.
• "화면 함수는 한 번 컴파일, 이벤트 함수는 서버에서 매번 실행"을 자기 말로 설명할 수 있다.