최대 4명까지 참여 가능한 크로스 플랫폼 실시간 채팅 서비스
- 4명 제한: 방당 최대 4명까지만 입장 가능
- 실시간 채팅: HTTP Polling 기반 실시간 메시지 송수신
- 크로스 플랫폼: PC, 모바일, 태블릿 모든 기기에서 접속 가능
- 브라우저 호환: Chrome, Safari, Firefox, Edge 등 모든 브라우저 지원
- 영구 저장: Upstash Redis로 안정적인 데이터 보관
- 직관적 UI: 깔끔하고 사용하기 쉬운 인터페이스
- 반응형 디자인: 모바일 최적화된 반응형 레이아웃
- 실시간 상태: 연결 상태 및 참여자 수 실시간 표시
- 메시지 히스토리: 늦게 참여해도 최근 100개 메시지 확인 가능
- 자동 정리: 24시간 후 비활성 방 자동 삭제
- 터치 최적화: 모바일 터치 인터페이스 완전 지원
- 햄버거 메뉴: 모바일에서 사이드바 토글 기능
- 반응형 텍스트: 화면 크기에 따른 텍스트 크기 자동 조정
- 안정적 연결: HTTP Polling으로 모든 환경에서 안정적 작동
- Framework: Next.js 15 (App Router)
- Library: React 19
- Language: TypeScript
- Styling: Tailwind CSS
- Communication: HTTP REST API + Polling
- Runtime: Node.js (Serverless)
- Database: Upstash Redis (무료)
- API: REST API Routes
- Deployment: Vercel (Serverless)
- Hosting: Vercel
- Database: Upstash Redis (Tokyo)
- CDN: Vercel Edge Network
- Domain: vercel.app
# 1. 저장소 클론
git clone https://github.com/bulhwi/quad-chat.git
cd quad-chat
# 2. 의존성 설치
npm install
# 3. 개발 서버 실행
npm run dev
# 4. 브라우저에서 접속
http://localhost:3001이 애플리케이션은 Upstash Redis를 사용하여 실시간 채팅 데이터를 저장합니다. 배포하기 전에 Redis 데이터베이스를 설정해야 합니다.
| 항목 | 무료 플랜 제공량 | 비고 |
|---|---|---|
| 일일 요청 수 | 10,000 requests | 채팅 앱에 충분 |
| 데이터 크기 | 256MB | 수천 개 방 저장 가능 |
| 동시 연결 | 제한 없음 | 무제한 사용자 |
| 데이터 보관 | 영구 보관 | 삭제되지 않음 |
| 지역 | 전 세계 | Tokyo 리전 사용 권장 |
- https://console.upstash.com 접속
- "Sign up with GitHub" 클릭
- GitHub 계정으로 무료 회원가입 완료
- "Create Database" 버튼 클릭
- 설정값 입력:
Name: quad-chat-db Region: Tokyo, Japan (또는 가장 가까운 지역) Type: Regional (기본값) - "Create" 버튼 클릭
- 생성된 데이터베이스 클릭
- "REST API" 탭 선택
- 다음 2개 값 복사:
UPSTASH_REDIS_REST_URL="https://xxx-xxx-xxx.upstash.io" UPSTASH_REDIS_REST_TOKEN="AXXXxxxxxxxxxxxxxxxxxxxxxxxxx"
- https://vercel.com/dashboard 접속
- quad-chat 프로젝트 클릭
- Settings → Environment Variables 이동
- 다음 2개 변수 추가:
Name: UPSTASH_REDIS_REST_URL Value: [3단계에서 복사한 URL] Name: UPSTASH_REDIS_REST_TOKEN Value: [3단계에서 복사한 토큰] - "Save" 클릭
로컬에서 개발하려면 .env.local 파일을 생성하세요:
# .env.local 파일 생성
UPSTASH_REDIS_REST_URL=your_redis_url_here
UPSTASH_REDIS_REST_TOKEN=your_redis_token_here- Upstash 콘솔에서 실시간 사용량 확인 가능
- Metrics 탭에서 요청 수, 저장 용량 등 확인
- 무료 한도 초과 시 자동 알림
{
"room:abc123": {
"users": [
{
"id": "user_123",
"nickname": "사용자1",
"joinedAt": "2024-01-01T00:00:00Z"
}
],
"messages": [
{
"id": "msg_123",
"userId": "user_123",
"nickname": "사용자1",
"message": "안녕하세요!",
"timestamp": "2024-01-01T00:00:00Z"
}
]
}
}- 무료 플랜 일일 10,000 요청 제한 (충분함)
- TTL 24시간 설정으로 자동 방 정리
- Tokyo 리전 사용 시 한국에서 빠른 속도
- HTTPS만 지원 (HTTP는 불가)
- 라이브 서비스: quad-chat.vercel.app
- 자동 배포: GitHub 푸시 시 자동 배포
- 빌드 상태: ✅ 정상 빌드 완료
# 1. 저장소 포크 또는 클론
git clone https://github.com/bulhwi/quad-chat.git
cd quad-chat
# 2. Vercel 웹사이트 접속
# https://vercel.com 방문
# 3. GitHub 계정으로 로그인
# 4. "Add New..." → "Project" 클릭
# 5. GitHub 저장소 선택
# - bulhwi/quad-chat 또는 본인의 포크된 저장소 선택
# 6. 프로젝트 설정 (기본값 유지)
# - Framework Preset: Next.js
# - Root Directory: ./
# - Build Command: npm run build
# - Output Directory: .next
# - Install Command: npm install
# 7. "Deploy" 클릭# 1. Vercel CLI 설치
npm install -g vercel
# 2. Vercel 로그인
vercel login
# 3. 프로젝트 디렉토리에서 배포
vercel
# 4. 프로덕션 배포
vercel --prod가장 간단하고 안정적인 방법입니다:
-
Vercel에서 프로젝트 연결:
- Vercel 대시보드에서 "Add New..." → "Project"
- GitHub 저장소
bulhwi/quad-chat선택 - "Import" 클릭
-
자동 배포 설정:
- main 브랜치에 푸시 시 자동 배포
- Pull Request 시 프리뷰 배포
- 토큰 설정 불필요
- Node.js 버전: 20.x (자동 감지)
- 빌드 명령어:
npm run build - 시작 명령어:
npm start
| 변수명 | 설명 | 기본값 |
|---|---|---|
UPSTASH_REDIS_REST_URL |
Redis 연결 URL | 필수 설정 |
UPSTASH_REDIS_REST_TOKEN |
Redis 인증 토큰 | 필수 설정 |
NODE_ENV |
환경 모드 | production |
// vercel.json (필요시)
{
"buildCommand": "npm run build",
"outputDirectory": ".next",
"framework": "nextjs",
"regions": ["icn1"] // 서울 리전
}브라우저 ←→ Next.js Dev Server (3001) ←→ REST API Routes ←→ Upstash Redis
브라우저 ←→ Vercel Edge ←→ Next.js App ←→ API Routes (/api/rooms/[roomId])
↓
Upstash Redis (Tokyo)
- Redis 설정: Upstash Redis 환경변수 필수 설정 (URL, TOKEN)
- CORS 설정: 모든 오리진 허용으로 설정됨 (
Access-Control-Allow-Origin: *) - 데이터 저장소: Upstash Redis 기반 영구 저장 (24시간 TTL)
- 스케일링: 서버리스 특성상 Redis로 상태 공유
- 요청 제한: 무료 플랜 일일 10,000 요청 한도
- 메인 페이지 로딩
- 닉네임 입력 및 방 생성
- 방 코드로 참여
- 실시간 메시지 송수신
- 4명 제한 확인
- 모바일에서 접속 테스트
- 다양한 브라우저에서 테스트
- Vercel 로그: Vercel 대시보드에서 함수 로그 확인
- 브라우저 콘솔: HTTP 요청/응답 상태 확인
- Network 탭: REST API 호출 모니터링
- Upstash 콘솔: Redis 데이터 및 사용량 확인
- quad-chat.vercel.app 접속
- 원하는 닉네임 입력 (최대 20자)
- "새 방 만들기" 버튼 클릭
- 생성된 7자리 방 코드를 친구들에게 공유
- 사이트 접속 후 닉네임 입력
- "기존 방 참여하기" 클릭
- 받은 방 코드 입력
- "방 참여하기" 클릭
- 하단 입력창에 메시지 입력
- Enter 키 또는 "전송" 버튼으로 메시지 전송
- 우측 사이드바에서 참여자 목록 확인
- 모바일에서는 햄버거 메뉴로 사이드바 토글
- 사이드바 열기: 좌상단 햄버거 메뉴 탭
- 방 코드 복사: 방 정보에서 "복사" 버튼 탭
- 메시지 스크롤: 터치로 메시지 히스토리 스크롤
quad-chat/
├── 📁 app/ # Next.js App Router
│ ├── 📄 layout.tsx # 글로벌 레이아웃
│ ├── 📄 page.tsx # 메인 페이지 (방 생성/참여)
│ ├── 📄 globals.css # 글로벌 스타일
│ ├── 📁 chat/[roomId]/ # 동적 채팅방 라우트
│ │ └── 📄 page.tsx # 채팅방 페이지
├── 📁 pages/ # Pages Router (API 전용)
│ └── 📁 api/
│ └── 📁 rooms/
│ └── 📄 [roomId].js # REST API 라우트 (Redis 연동)
├── 📁 lib/ # 유틸리티 라이브러리
│ ├── 📄 redis.ts # Redis 연결 및 데이터 관리
│ ├── 📄 api.ts # HTTP 클라이언트
│ └── 📄 socket.ts # Socket.io (로컬 개발용)
├── 📁 .github/workflows/ # GitHub Actions
│ └── 📄 korean-release.yml # 🇰🇷 한국어 릴리즈 노트 자동화
├── 📁 scripts/ # 자동화 스크립트
│ └── 📄 generate-korean-release.js # 한국어 릴리즈 노트 생성기
├── 📁 docs/ # 프로젝트 문서
│ └── 📄 VERSIONING.md # 버전 관리 가이드라인
├── 📄 CHANGELOG.md # 🇰🇷 한국어 변경사항 기록
├── 📄 server.js # 로컬 개발용 커스텀 서버
├── 📄 package.json # 프로젝트 설정 (v1.0.1)
├── 📄 tailwind.config.ts # Tailwind CSS 설정
├── 📄 tsconfig.json # TypeScript 설정
└── 📄 next.config.js # Next.js 설정
| 파일 | 역할 |
|---|---|
app/page.tsx |
메인 페이지: 닉네임 입력, 방 생성/참여 |
app/chat/[roomId]/page.tsx |
채팅방: HTTP Polling 기반 실시간 채팅 |
pages/api/rooms/[roomId].js |
REST API: 방 관리, 메시지 송수신 |
lib/redis.ts |
Redis 연결: 데이터 저장/조회 관리 |
lib/api.ts |
HTTP 클라이언트: API 호출 관리 |
CHANGELOG.md |
🇰🇷 한국어 변경사항 기록 및 릴리즈 히스토리 |
.github/workflows/korean-release.yml |
🤖 한국어 릴리즈 노트 자동화 워크플로우 |
scripts/generate-korean-release.js |
한국어 릴리즈 노트 생성 스크립트 |
docs/VERSIONING.md |
Semantic Versioning 가이드라인 |
server.js |
로컬 개발 서버: Socket.io + Next.js (로컬용) |
# 🚀 개발 관련
npm run dev # 로컬 개발 서버 (커스텀 서버 + Socket.io)
npm run dev:next # Next.js 개발 서버만 실행
# 🏗️ 빌드 관련
npm run build # 프로덕션 빌드
npm run start # 프로덕션 서버 실행
# 🧹 코드 품질
npm run lint # ESLint 실행
npm run type-check # TypeScript 타입 검사
# 📦 의존성 관리
npm install # 의존성 설치
npm update # 의존성 업데이트# main - 프로덕션 안정 버전
# develop - 개발 통합 브랜치
# feature/* - 기능별 개발 브랜치# 1. 저장소 클론
git clone https://github.com/bulhwi/quad-chat.git
cd quad-chat
# 2. 의존성 설치
npm install
# 3. 기능 브랜치 생성
git checkout develop
git checkout -b feature/new-feature
# 4. 개발 서버 실행
npm run dev
# 5. 코드 수정 및 테스트
# http://localhost:3001에서 실시간 확인
# 6. 빌드 테스트
npm run build
# 7. 변경사항 커밋
git add .
git commit -m "feat: 새로운 기능 추가"
# 8. develop 브랜치로 PR 생성
git push origin feature/new-feature
# GitHub에서 feature/* → develop PR 생성
# 9. develop에서 테스트 후 main으로 릴리즈 PR
# develop → main PR 생성 및 머지
# 10. 릴리즈 태그 생성 (자동 릴리즈 노트 생성)
git checkout main
git pull origin main
git tag v1.x.x -m "릴리즈 메시지"
git push origin v1.x.x- MAJOR (1.0.0 → 2.0.0): 호환성 중단 변경사항
- MINOR (1.0.0 → 1.1.0): 새로운 기능 추가 (하위 호환)
- PATCH (1.0.0 → 1.0.1): 버그 수정 및 성능 개선
# 태그 푸시 시 자동 실행되는 GitHub Actions
git tag v1.1.0 -m "이모티콘 기능 추가"
git push origin v1.1.0
# ↓ 자동으로 실행됨
# 1. CHANGELOG.md에서 변경사항 추출
# 2. 한국어 친화적 릴리즈 노트 생성
# 3. GitHub Release 자동 생성
# 4. 한국어 우선 정책 적용# 기능 개발 완료 시 CHANGELOG.md 업데이트
## [미배포] - Unreleased
### 추가됨
- 새로운 기능 설명
# 릴리즈 시 버전과 날짜 업데이트
## [1.1.0] - 2025-09-28 - ✨ 새로운 기능- 에디터: VS Code
- 확장: ES7+ React/Redux/React-Native snippets, Tailwind CSS IntelliSense
- 브라우저: Chrome (개발자 도구)
- 터미널: 통합 터미널 또는 별도 터미널
- Node.js: 20.x 이상
- npm: 10.x 이상
- 한국어 우선 정책: 모든 릴리즈 노트는 한국어로 먼저 작성
- 사용자 친화적: 기술 용어보다 일반 사용자가 이해하기 쉬운 표현
- 자동화: GitHub Actions를 통한 완전 자동화
- Semantic Versioning: 버전별 이모지와 친화적 제목 자동 생성
| 영어 용어 | 한국어 용어 |
|---|---|
| Breaking Changes | 호환성 중단 변경사항 |
| Migration | 업그레이드 방법 |
| Deprecated | 사용 중단 예정 |
| Performance | 성능 최적화 |
| Security | 보안 강화 |
| Bug Fix | 오류 수정 |
# 🐛 Quad Chat v1.0.1 - 버그 수정 및 개선
안녕하세요! Quad Chat의 새로운 업데이트가 출시되었습니다! 🎉
## 🔧 수정사항
- GitHub Actions 권한 문제 해결
- 릴리즈 자동화 개선
- 워크플로우 안정성 향상
## 🔄 업그레이드 방법
별도 작업 없이 자동으로 업데이트됩니다. 브라우저를 새로고침하면 새 기능을 사용할 수 있어요!# 로컬에서 릴리즈 노트 미리보기
node scripts/generate-korean-release.js v1.1.0
# 생성된 release-notes-ko.md 파일 확인
cat release-notes-ko.mdCHANGELOG.md: 한국어 변경사항 기록docs/VERSIONING.md: 버전 관리 가이드라인- GitHub Releases: 모든 릴리즈 목록
- 연결 문제: 브라우저 콘솔에서 HTTP 요청 상태 확인
- Redis 오류: Upstash 콘솔에서 연결 상태 및 사용량 확인
- 환경변수 오류: Vercel 대시보드에서 환경변수 설정 확인
- 모바일 이슈: 다른 브라우저(Safari, Chrome)에서 테스트
- 배포 문제: Vercel 대시보드에서 빌드 로그 확인
- 이 저장소를 포크
- develop 브랜치에서 새 기능 브랜치 생성 (
git checkout -b feature/amazing-feature) - 변경사항 커밋 (
git commit -m 'Add some amazing feature') - 브랜치에 푸시 (
git push origin feature/amazing-feature) - develop 브랜치로 Pull Request 생성
- 코드 리뷰 및 승인 후 머지
🔒 브랜치 보호 규칙: main 및 develop 브랜치는 PR을 통해서만 변경 가능하며, 모든 PR은 리뷰 승인이 필요합니다.
이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.
박불휘 (bulhwi)
이 프로젝트는 실시간 웹 채팅의 간단하면서도 효과적인 구현을 목표로 제작되었습니다. 사용해주시고 피드백을 남겨주신 모든 분들께 감사드립니다.
- 🎭 이모티콘 기능 - 다양한 이모지 반응 추가
- 📷 이미지 첨부 기능 - 사진 공유 가능
- 📱 모바일 최적화 - 더욱 개선된 모바일 UX
- 🔔 알림 시스템 - 새 메시지 알림 기능
- ⌨️ 타이핑 인디케이터 - 실시간 입력 상태 표시
- WebSocket 연결 옵션 추가 (선택적)
- 방 관리 기능 확장 (비공개방, 초대 링크)
- 사용자 프로필 시스템 도입
- 채팅 히스토리 영구 보관 옵션
🤖 Generated with Claude Code
💡 팁: 이 README는 프로젝트와 함께 지속적으로 업데이트됩니다. Star ⭐를 눌러 최신 업데이트를 받아보세요!