GitHub - gitkim95/Tsen-front

🏓 Transcendence Frontend - Real-time Multiplayer Pong Game

실시간 멀티플레이어 퐁 게임을 즐길 수 있는 웹 애플리케이션입니다. WebSocket을 활용한 실시간 통신으로 친구들과 함께 클래식 퐁 게임을 즐기고, 토너먼트에 참여해보세요!

🎮 주요 기능

🔐 인증 시스템

OAuth 로그인: Google, 42 계정으로 간편 로그인
사용자 프로필: 프로필 편집, 비밀번호 변경
보안: JWT 토큰 기반 인증 시스템

🏟️ 로비 시스템

로비 생성: 친구들과 함께 플레이할 로비 생성
로비 목록: 참여 가능한 로비 실시간 조회
준비 시스템: 모든 플레이어가 준비 완료 시 게임 시작
실시간 채팅: 로비 내 실시간 채팅 기능

🎯 게임 시스템

실시간 퐁 게임: WebSocket 기반 실시간 멀티플레이어 게임
토너먼트: 여러 플레이어가 참여하는 토너먼트 시스템
매칭 시스템: 자동 매칭 및 브라켓 생성
게임 통계: 개인 전적 및 게임 기록 관리

👥 소셜 기능

친구 시스템: 친구 추가 및 온라인 상태 확인
사용자 정보: 다른 사용자의 프로필 및 전적 조회
대시보드: 랭킹 시스템 및 리더보드

🛠️ 기술 스택

Frontend

TypeScript: 타입 안전성을 보장하는 JavaScript 슈퍼셋
Tailwind CSS: 유틸리티 우선 CSS 프레임워크
Vite: 빠른 개발 서버 및 빌드 도구
Socket.IO Client: 실시간 양방향 통신

Development Tools

PostCSS: CSS 후처리 도구
Autoprefixer: 브라우저 호환성을 위한 CSS 벤더 프리픽스 자동 추가
ESLint & Prettier: 코드 품질 및 일관성 유지

📁 프로젝트 구조

tsen-front/
├── src/
│   ├── components/           # UI 컴포넌트
│   │   ├── login/           # 로그인/회원가입 컴포넌트
│   │   ├── game/            # 게임 컴포넌트
│   │   ├── lobby/           # 로비 관련 컴포넌트
│   │   ├── friend/          # 친구 시스템 컴포넌트
│   │   ├── user/            # 사용자 관리 컴포넌트
│   │   ├── dashboard/       # 대시보드 컴포넌트
|   |   ├── auth/            # OAuth 인증 컴포넌트
|   |   └── header/          # 헤더 컴포넌트
│   ├── pages/               # 페이지 레이아웃
│   ├── utils/               # 유틸리티 함수
│   │   ├── auth.ts          # 인증 관리
│   │   ├── user.ts          # 사용자 관리
│   │   └── friendWebSocket.ts # 친구 WebSocket 관리
│   ├── types/               # TypeScript 타입 정의
│   ├── styles/              # 스타일 파일
│   ├── router.ts            # 클라이언트 사이드 라우팅
│   └── app.ts               # 애플리케이션 진입점
├── public/                  # 정적 파일
├── dist/                    # 빌드 결과물
├── package.json
├── tsconfig.json
├── tailwind.config.js
├── vite.config.js
└── README.md

🚀 시작하기

사전 요구사항

Node.js: v20.0.0 이상
npm 또는 yarn
백엔드 서버: Transcendence 백엔드 서버가 실행 중이어야 합니다

설치

저장소 클론

git clone <repository-url>
cd tsen-front

의존성 설치
```
npm install
# 또는
yarn install
```

환경 변수 설정

# .env 파일 생성 (프로젝트 루트)
VITE_API_BASE_URL=http://localhost:3000
VITE_SOCKET_BASE_URL=http://localhost:3000

개발 서버 실행

npm run dev
# 또는
yarn dev

개발 서버는 기본적으로 http://localhost:8080에서 실행됩니다.

빌드

npm run build
# 또는
yarn build

빌드된 파일은 dist/ 폴더에 생성됩니다.

🗂 HTML Template & Global Assets

index.html 은 크리티컬 렌더링 경로를 최소화하기 위해 다음 요소를 포함합니다.

요소	목적
`<meta name="viewport">`	모바일 최소 UI 지연
`<link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>`	Pretendard CDN 연결 핸드셰이크 사전 완료 → FOUT 최소화
Pretendard 웹폰트 CDN	가독성 높은 기본 폰트, 9 weights 지원
모듈 엔트리 `src/app.ts`	Vite + TypeScript SPA 진입점

Tailwind 의 입력/메인/Friend 전용 CSS를 별도 분리하여 css-tree-shaking 효율을 극대화했습니다.

🎯 주요 컴포넌트

GameComponent

WebSocket을 통한 실시간 퐁 게임 구현
Canvas를 사용한 게임 렌더링
키보드 입력 처리 및 게임 로직

LobbySystem

LobbyListComponent: 로비 목록 표시 및 필터링
LobbyDetailComponent: 로비 상세 정보 및 실시간 상태 업데이트
LobbyDetailService: 로비 관련 API 통신 및 WebSocket 관리

AuthManager

JWT 토큰 관리
자동 토큰 갱신
OAuth 인증 처리

🔄 실시간 통신

이 애플리케이션은 Socket.IO를 사용하여 다음과 같은 실시간 기능을 제공합니다:

WebSocket 이벤트

로비 이벤트

lobby:ready - 플레이어 준비 상태 변경
lobby:player_change - 플레이어 입장/퇴장
lobby:update - 로비 상태 업데이트
match:created - 매칭 생성 완료

게임 이벤트

game:started - 게임 시작
game:completed - 게임 완료
tournament:completed - 토너먼트 완료

채팅 이벤트

chat:message - 채팅 메시지
chat:typing - 타이핑 상태
user:connected/disconnected - 사용자 연결 상태

🎨 스타일링

Tailwind CSS 커스터마이징

프로젝트는 커스텀 Tailwind 설정을 사용합니다:

컬러 팔레트: 게임에 최적화된 8가지 컬러 시스템
글래스모피즘 효과: 투명도를 활용한 모던한 UI
반응형 디자인: 모든 디바이스에서 최적화된 경험
커스텀 애니메이션: 부드러운 사용자 경험을 위한 애니메이션

주요 컬러 테마

Primary: Cornflower Blue (#7B9BD1)
Secondary: Viola (#A888C2)
Neutral: Gardenia (#F5F5DC)
Success: Tendril (#8FBC8F)

🌐 API 통신

인증 API

POST /auth/login - 로그인
POST /auth/register - 회원가입
GET /auth/google - Google OAuth
GET /auth/42 - 42 OAuth

로비 API

GET /lobbies - 로비 목록 조회
POST /lobbies - 로비 생성
POST /lobbies/:id/join - 로비 입장
POST /lobbies/:id/ready_state - 준비 상태 변경

사용자 API

GET /users/:id - 사용자 정보 조회
PUT /users/:id - 사용자 정보 수정
GET /users/:id/stats - 사용자 전적 조회

📱 주요 페이지

인증 페이지

/login - 로그인
/signup - 회원가입

메인 페이지

/ - 로비 목록 (홈)
/lobby/:id - 로비 상세
/game/:gameId/:tournamentId - 게임 플레이

사용자 페이지

/user/:id - 사용자 프로필
/user/:id/stats - 사용자 전적
/profile/edit - 프로필 편집

기타

/dashboard - 대시보드 (랭킹)

🔧 개발 가이드

컴포넌트 개발

모든 컴포넌트는 TypeScript로 작성
Component 기본 클래스를 상속하여 구현
생명주기 메서드 (render(), destroy()) 구현 필수

서비스 레이어

API 통신은 전용 Service 클래스에서 처리
WebSocket 연결은 각 서비스에서 관리
에러 처리 및 로딩 상태 관리 포함

스타일 가이드

Tailwind CSS 유틸리티 클래스 우선 사용
커스텀 CSS는 최소한으로 제한
반응형 디자인 필수 고려

🐳 Docker & Containerization

멀티-스테이지 구조

Stage	Base 이미지	주요 작업	비고
builder	`node:20-alpine`	• 의존성 설치 • `npm run build` 로 Vite 정적 빌드 • `.env.production` → `.env` 복사	빌드 도구 포함
runtime	`alpine:latest`	• `dist/` 산출물만 복사 • 경량 컨테이너(≈ 5 MB)	불필요 종속성 제거로 보안·용량↑

결과 이미지는 실행 시 정적 파일만 서빙합니다. 런타임 Node.js 프로세스가 필요하지 않으므로 Nginx·CloudFront 등과 조합하면 초경량 배포가 가능합니다.

환경 변수

.env.production

VITE_API_BASE_URL=https://api.example.com
VITE_SOCKET_BASE_URL=wss://socket.example.com

빌드 시 자동으로 .env.production ➜ .env 로 복사됩니다.

🚀 배포

정적 파일 서빙

빌드 결과물을 정적 파일 서버에 배포:

Nginx
Apache
CDN (CloudFront, Cloudflare 등)

빌드 & 실행

이미지를 로컬에서 빌드

docker build -t tsen-front .

정적 파일만 테스트(예: serve 패키지 이용)

docker run -it --rm -p 8080:80
-v $(pwd)/dist:/usr/share/nginx/html nginx:alpine

환경 변수

프로덕션 환경에서는 다음 환경 변수를 설정해주세요:

VITE_API_BASE_URL=v1
VITE_SOCKET_BASE_URL=

코딩 컨벤션

TypeScript strict 모드 사용
ESLint 규칙 준수
의미있는 커밋 메시지 작성
컴포넌트 및 함수 문서화

🚀 통합 배포(Nginx + Backend)

프론트엔드 정적 결과물(dist/)과 백엔드(Node/Fastify) 를 단일 Nginx 리버스 프록시로 묶어 배포할 수 있습니다.
자세한 Docker-Compose 예제는 아래 레포에서 확인하세요.

👉 전체 스택 배포 가이드 보기

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🔗 관련 링크

📞 문의

프로젝트에 대한 질문이나 제안사항이 있으시면 Issue를 생성하거나 이메일로 연락주세요.

즐거운 게임 되세요! 🏓

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
Dockerfile		Dockerfile
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
readme.md		readme.md
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

🏓 Transcendence Frontend - Real-time Multiplayer Pong Game

🎮 주요 기능

🔐 인증 시스템

🏟️ 로비 시스템

🎯 게임 시스템

👥 소셜 기능

🛠️ 기술 스택

Frontend

Development Tools

📁 프로젝트 구조

🚀 시작하기

사전 요구사항

설치

개발 서버 실행

빌드

🗂 HTML Template & Global Assets

🎯 주요 컴포넌트

GameComponent

LobbySystem

AuthManager

🔄 실시간 통신

WebSocket 이벤트

🎨 스타일링

Tailwind CSS 커스터마이징

주요 컬러 테마

🌐 API 통신

인증 API

로비 API

사용자 API

📱 주요 페이지

인증 페이지

메인 페이지

사용자 페이지

기타

🔧 개발 가이드

컴포넌트 개발

서비스 레이어

스타일 가이드

🐳 Docker & Containerization

멀티-스테이지 구조

환경 변수

🚀 배포

정적 파일 서빙

빌드 & 실행

환경 변수

코딩 컨벤션

🚀 통합 배포(Nginx + Backend)

📄 라이선스

🔗 관련 링크

📞 문의

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages