React + Python FastAPI로웹 게임 만들기 #1

🎮 사이드 프로젝트

React + Python FastAPI로
웹 게임 만들기 #1

프로젝트 세팅 — 폴더 구조, Vite, FastAPI 환경 구성까지

2026.04.22  ·  환경 세팅  ·  React · FastAPI · Vite

📋 목차

1. 왜 이 기술 스택을 골랐는가
2. 전체 폴더 구조
3. PowerShell 실행 정책 해제
4. React + Vite 프론트엔드 세팅
5. Python FastAPI 백엔드 세팅
6. CORS 설정과 API 구조
7. 진행 상황 & 다음 편 예고

1 왜 이 기술 스택을 골랐는가

이번에 만들 게임은 장애물을 피해 최대한 오래 버티는 무한 달리기 게임이다. 시간이 지날수록 속도가 빨라지고, 기록을 닉네임과 함께 리더보드에 남길 수 있다.

게임 로직 자체는 JavaScript로 충분하지만, 점수 저장과 리더보드를 여러 사람이 공유하려면 서버가 필요하다. 그래서 프론트와 백엔드를 분리했다.

⚛️ React Frontend

게임 화면, UI, 캐릭터 애니메이션 등 모든 화면을 담당. 컴포넌트 단위로 나눠서 관리하기 쉽다.

⚡ Vite 빌드 도구

Create React App보다 훨씬 빠른 개발 서버. 저장하면 즉시 반영(HMR)되어 개발 속도가 빠르다.

🐍 FastAPI Backend

Python 기반 웹 프레임워크. 코드가 간결하고, 자동으로 API 문서(/docs)를 만들어줘서 테스트하기 편하다.

🦄 Uvicorn 서버

FastAPI를 실행시켜주는 ASGI 서버. --reload 옵션으로 코드 수정 시 자동 재시작된다.

💡

핵심 아이디어: 게임 화면(React)과 점수 저장(FastAPI)을 분리하면 나중에 어느 쪽이든 독립적으로 수정할 수 있다. React는 API 호출만 하면 되고, FastAPI는 데이터 처리만 담당한다.

2 전체 폴더 구조

프로젝트 루트를 D:\Lee_project\neon-runner\로 잡고, 프론트와 백엔드를 명확하게 분리했다.

D:\Lee_project\neon-runner\
├── frontend\     ← React + Vite 게임 화면
│   ├── src\
│   │   ├── App.jsx    ← 게임 메인 컴포넌트
│   │   └── main.jsx   ← React 진입점
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
└── backend\     ← Python FastAPI 점수 서버
    ├── venv\        ← Python 가상환경
    ├── main.py     ← FastAPI 서버 코드
    └── scores.json  ← 점수 저장 파일 (자동생성)

📁

왜 frontend / backend를 나눴나?
하나의 폴더에 다 넣으면 Python 패키지와 JS 패키지가 섞여서 관리가 어려워진다. 역할별로 폴더를 분리하면 나중에 배포할 때도 각각 독립적으로 올릴 수 있다.

3 PowerShell 실행 정책 해제

Windows에서 PowerShell로 npm 명령어를 처음 실행하면 이런 오류가 난다.

오류 메시지

npm : 이 시스템에서 스크립트를 실행할 수 없으므로
C:\Program Files\nodejs\npm.ps1 파일을 로드할 수 없습니다.
    + CategoryInfo : 보안 오류: (:) [], PSSecurityException

Windows PowerShell은 기본적으로 외부 스크립트 실행을 막아놓는다. npm은 내부적으로 .ps1 스크립트를 사용하기 때문에 이 정책을 완화해야 한다.

관리자 권한 PowerShell에서 아래 명령어를 실행한다.

PowerShell (관리자)

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

🔑

옵션 설명
-Scope CurrentUser — 현재 사용자에게만 적용 (시스템 전체 변경 X)
RemoteSigned — 로컬 스크립트는 허용, 인터넷에서 받은 스크립트는 서명 필요
→ 보안을 유지하면서 npm이 동작할 수 있는 최소한의 설정이다.

4 React + Vite 프론트엔드 세팅

frontend\ 폴더 안에서 Vite 프로젝트를 생성한다. .을 경로로 쓰면 현재 폴더에 바로 생성된다.

PowerShell

# frontend 폴더로 이동
cd D:\Lee_project\neon-runner\frontend

# Vite + React 프로젝트 생성 (현재 폴더에)
npm create vite@latest . -- --template react

# 패키지 설치
npm install

# 개발 서버 실행
npm run dev

설치 후 http://localhost:5173 에서 React 기본 화면이 뜨면 성공이다.

기본으로 생성된 파일 중 게임에 필요 없는 파일들을 정리한다.

PowerShell — 불필요한 파일 삭제

Remove-Item src\App.css
Remove-Item src\index.css
Remove-Item -Recurse src\assets

그리고 App.jsx와 main.jsx를 깔끔하게 초기화한다.

src/main.jsx

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

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

src/App.jsx — 초기화

export default function App() {
  return (
    <div>
      <h1>NEON RUNNER</h1>
    </div>
  )
}

✅

Vite를 쓰는 이유: 기존 Create React App(CRA)은 Webpack 기반으로 개발 서버가 느리고 설정이 복잡했다. Vite는 ESM(ES Module) 기반으로 동작해서 서버 시작이 수십 배 빠르고, HMR(코드 저장 즉시 반영)도 훨씬 빠르다.

5 Python FastAPI 백엔드 세팅

점수 저장과 리더보드 조회를 담당하는 API 서버를 Python으로 만든다.

먼저 가상환경(venv)을 만든다. 가상환경은 프로젝트별로 Python 패키지를 독립적으로 관리할 수 있게 해준다. 다른 프로젝트 패키지와 충돌하지 않는다.

PowerShell — 새 터미널

# backend 폴더로 이동
cd D:\Lee_project\neon-runner\backend

# 가상환경 생성
python -m venv venv

# 가상환경 활성화 (앞에 (venv) 표시 뜨면 성공)
venv\Scripts\activate

# FastAPI + 서버(uvicorn) 설치
pip install fastapi uvicorn

💡

왜 가상환경을 쓰나?
전역 Python 환경에 패키지를 설치하면 프로젝트마다 버전 충돌이 날 수 있다. venv로 격리하면 이 프로젝트에서만 사용하는 패키지 버전을 따로 관리할 수 있다.

이제 backend\main.py를 만든다. 이 파일 하나가 API 서버 전체다.

backend/main.py

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import json
import os

app = FastAPI()

# React 개발서버(5173)에서 오는 요청 허용
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_methods=["*"],
    allow_headers=["*"],
)

DB_FILE = "scores.json"

def load_scores():
    if not os.path.exists(DB_FILE):
        return []
    with open(DB_FILE, "r", encoding="utf-8") as f:
        return json.load(f)

def save_scores(scores):
    with open(DB_FILE, "w", encoding="utf-8") as f:
        json.dump(scores, f, ensure_ascii=False, indent=2)

# 점수 데이터 형태 정의
class ScoreEntry(BaseModel):
    nickname: str
    score: int
    time: float

# GET /leaderboard — 상위 20개 점수 조회
@app.get("/leaderboard")
def get_leaderboard():
    scores = load_scores()
    return scores[:20]

# POST /score — 점수 저장 후 순위 반환
@app.post("/score")
def post_score(entry: ScoreEntry):
    scores = load_scores()
    scores.append(entry.model_dump())
    scores.sort(key=lambda x: x["score"], reverse=True)
    save_scores(scores)
    rank = next(i+1 for i, s in enumerate(scores)
                 if s["nickname"] == entry.nickname
                 and s["score"] == entry.score)
    return {"rank": rank, "total": len(scores)}

서버 실행:

PowerShell

uvicorn main:app --reload

# 성공 시 출력:
# INFO:     Uvicorn running on http://127.0.0.1:8000

http://127.0.0.1:8000/leaderboard 에서 []가 보이면 API 정상 동작이다. http://127.0.0.1:8000/docs에서는 자동 생성된 API 문서도 볼 수 있다.

6 CORS 설정이 왜 필요한가

React는 localhost:5173에서 실행되고, FastAPI는 localhost:8000에서 실행된다. 브라우저는 기본적으로 다른 포트(출처)로 보내는 요청을 차단한다. 이것이 CORS(Cross-Origin Resource Sharing) 정책이다.

backend/main.py — CORS 설정 부분

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # React 주소만 허용
    allow_methods=["*"],                       # GET, POST 등 모두 허용
    allow_headers=["*"],                       # 모든 헤더 허용
)

⚠️

개발 환경 vs 배포 환경: 지금은 개발 편의를 위해 localhost:5173만 허용했다. 나중에 실제 서버에 배포할 때는 allow_origins를 실제 도메인으로 바꿔야 한다.

7 진행 상황 & 다음 편 예고

• 완료 D:\Lee_project\neon-runner\ 폴더 구조 생성
• 완료 PowerShell 실행 정책 해제
• 완료 React + Vite 프론트엔드 세팅 (localhost:5173)
• 완료 Python 가상환경 + FastAPI 세팅 (localhost:8000)
• 완료 점수 저장 / 리더보드 API 기본 구조 완성
• 다음편 Canvas로 게임 배경 + 캐릭터 그리기
• 예정 장애물 생성 + 충돌 감지
• 예정 점수 시스템 + FastAPI 연동

---

이번 편은 게임 코드보다 환경 세팅이 주였다.

세팅이 잘 되어있어야 나중에 헤매지 않는다.

다음 편에서는 본격적으로 게임 화면을 그린다.

▶ 다음편: Canvas로 캐릭터와 배경 그리기