![]() |
![]() |
|---|---|
| 이주석 | 강재진 |
| 역할 | 종류 |
|---|---|
| Library | |
| Programming Language | |
| Build Tool | |
| Routing | |
| Styling | |
| Code Quality | |
| Package Manager | |
| Browser Storage |
.env.example을 복사해 .env.local을 만들고 로컬 설정을 입력합니다. 배포 환경은 vercel.json의 same-origin /backend rewrite를 사용하므로 API Gateway 주소를 프론트 환경변수로 넣지 않습니다. Spotify callback 주소와 성공·실패 리다이렉트 주소는 백엔드와 Spotify Dashboard에서 관리합니다.
# 로컬에서만 사용
VITE_API_BASE_PATH=/api
VITE_DEV_API_TARGET=http://127.0.0.1:8080로그인 버튼은 배포에서 현재 프론트 origin의 /backend/v1/auth/spotify/login으로 이동합니다. 백엔드가 state 쿠키를 설정하고 Spotify로 302 이동하므로, 프론트에서 callback 주소나 state 값을 만들지 않습니다.
로컬에서는 Vite의 /api 프록시를 통해 백엔드에 연결합니다.
VITE_API_BASE_PATH=/api
VITE_DEV_API_TARGET=http://127.0.0.1:8080Spotify 로그인 문제를 해결하는 동안 로그인 뒤 화면만 개발해야 한다면, 개인 .env.local에 아래 값을 추가할 수 있습니다. 이 값은 pnpm dev에서만 적용되며 배포 빌드에서는 무시됩니다.
VITE_DEV_AUTH_BYPASS=true이 우회는 화면 접근만 열어 줍니다. 실제 인증이 필요한 API 요청은 백엔드의 테스트용 Access Token 또는 정상 로그인 세션이 필요합니다.
Vercel에는 VITE_API_BASE_URL을 등록하지 않습니다. vercel.json의 rewrite가 /backend/* 요청을 API Gateway로 전달하므로, 프론트의 모든 API와 Spotify 로그인은 같은 사이트의 /backend/v1/... 경로를 사용합니다. Refresh Token 쿠키를 전달하려면 인증 API 요청의 credentials: "include"를 유지해야 합니다. Spotify OAuth callback은 백엔드와 Spotify Dashboard에 아래 주소로 등록되어 있어야 합니다.
https://c635a7u5c3.execute-api.ap-northeast-2.amazonaws.com/api/v1/auth/spotify/callback
백엔드의 Refresh Token 쿠키 Path도 프록시 경로에 맞춰 /backend/v1/auth 또는 /backend/v1/auth/spotify로 설정되어야 합니다. Spotify Dashboard의 Redirect URI와 백엔드의 성공·실패 리다이렉트 설정을 변경했다면 백엔드와 프론트를 함께 재배포해야 합니다.
📁 파일/폴더 컨벤션
- 폴더/파일명: kebab-case
- 컴포넌트: PascalCase
- 함수/훅/유틸: camelCase
- 상수: UPPER_SNAKE_CASE
- 역할 접미사 권장:
-page,-layout,-view,-card,-modal… - 훅 파일명:
use-*.ts
상세:
coding.md,file-folder.md
🎨 스타일 가이드
global.css는 토큰·reset·타이포그래피·공통 Skeleton 효과의 전역 진입점으로 사용- 색상·폰트·여백 등 공통 값은
tokens.css의 CSS 변수 사용 - 타이포그래피는
typography.css의 전역 클래스 또는 폰트 토큰 사용 - 반복되는 UI는
components/common의 공통 컴포넌트를 import하여 사용 - 공통 UI와 페이지·기능 스타일은 소유 TSX가 역할별 CSS 파일을 직접 import
- Inline style과 임의의 색상·폰트 크기 하드코딩 지양
- Figma SVG 에셋은
assets/icons에서 직접 import하여 사용
상세:
style-guide.md
📁 절대 경로(alias)
@/*→src/*- 예:
@/pages/login-page,@/components/common/button,@/assets/icons/spotify-icon.svg - 상위 폴더를 넘나드는 import는 alias를 사용하고, 같은 폴더 내부에서는 상대 경로 사용
- TypeScript의
paths와 Vite의resolve.alias설정을 함께 유지
🤝 협업 및 PR 검사
- VS Code Clone부터 Issue, branch, Claude Code, Commit, PR, Merge까지 순서대로 진행
- 작업 branch 형식:
feat/#이슈번호/작업-타이틀 - PR마다 GitHub Actions에서
pnpm lint와pnpm build실행 - GitHub Conflict와 팀 코드 리뷰 확인 후 Merge
📑 Commit Convention
우리 프로젝트는 다음과 같은 커밋 규칙을 따릅니다.| 타입 | 의미 |
|---|---|
| feat | 새로운 기능 추가 |
| fix | 버그 수정 |
| chore | 빌드/도구/패키지 설정 등 잡무 변경 |
| style | 코드 스타일 변경 (포맷팅, 세미콜론 등) |
| hotfix | 긴급 버그 수정 |
| docs | 문서 관련 변경 (README 등) |
| refactor | 코드 리팩터링 (기능 변화 없음) |
| test | 테스트 코드 추가/수정 |
| init | 프로젝트 초기 설정/세팅 |
| build | 빌드 관련 변경 (배포, 빌드 설정 등) |
- scope: 선택 (비워도 허용)
- subject: 마침표 금지
- header: 최대 100자

