Need U Frontend Wiki

서비스 바로가기

개발 일정

기간	주요 작업
MM/DD ~	작업 내용

컨벤션 룰

코드 컨벤션 (Prettier & ESLint)

네이밍 규칙

항목	케이스 규칙
컴포넌트명	PascalCase
컴포넌트 파일명	PascalCase
Hook	camelCase, `use` 접두사 사용
Hook 파일명	camelCase
변수명	camelCase
Boolean 변수	camelCase, `is` / `has` / `can` 접두사 사용
함수명	camelCase, 동사 + 명사 형태
이벤트 핸들러	camelCase, 내부 `handle~` / Props `on~`
전역 상수	UPPER_SNAKE_CASE
Type / Interface	PascalCase
폴더명	kebab-case, 기본적으로 복수형 사용
일반 파일명	camelCase
서버 응답 데이터	API 명세 기준 사용

네이밍 예시

항목	예시
Component	`LoginButton`, `UserProfileCard`
Component File	`LoginButton.tsx`
Hook	`useUserProfile`, `useOutsideClick`
Hook File	`useUserProfile.ts`
Variable	`loginButton`, `users`, `posts`
Boolean	`isLoading`, `hasError`, `canSubmit`
Function	`getUserName`, `updatePosts`
Event Handler	`handleClick`, `onClick`
Constant	`MAX_RETRY_COUNT`
Type / Interface	`LoginButtonProps`, `UserResponse`
Directory	`components`, `image-files`
File	`formatDate.ts`, `logo.png`

Prettier

옵션	값	설명
trailingComma
tabWidth
semi
singleQuote
bracketSpacing
jsxBracketSameLine
printWidth

ESLint

항목	설정 내용
기본 설정
TypeScript 설정
글로벌 환경
무시 폴더
플러그인
커스텀 룰

깃 브랜치 전략

기본 브랜치

브랜치	설명
main	항상 배포 가능한 상태를 유지하는 기본 브랜치
dev	별도로 사용하지 않으며 모든 작업 브랜치는 `main`을 기준으로 생성

main 브랜치는 항상 배포 가능한 상태를 유지
main 브랜치 직접 Push 금지
모든 작업은 GitHub Issue를 기반으로 작업 브랜치 생성
작업 완료 후 main 브랜치로 Pull Request 생성
Pull Request Review 및 Status Check 통과 후 Merge
Merge가 완료된 작업 브랜치는 즉시 삭제

Branch Protection Rules

Require a pull request before merging
Require 1인 이상 Approve
- Backend 개발자 1인 이상 확인
Require status checks to pass
- lint
- build
직접 Push 금지
Force Push 금지

작업 브랜치 네이밍 규칙

형식:

{message}/{issue-number}-{작업명}

브랜치 타입	네이밍 패턴
기능 추가	`feature/{issue-number}-{작업명}`
버그 수정	`fix/{issue-number}-{작업명}`
리팩토링	`refactor/{issue-number}-{작업명}`
문서 수정	`docs/{issue-number}-{작업명}`
테스트	`test/{issue-number}-{작업명}`
CI/CD	`ci-cd/{issue-number}-{작업명}`

예시:

feature/3-login-page
fix/12-login-error
refactor/21-user-query
docs/25-update-wiki
test/31-login-form
ci-cd/40-deploy-workflow

브랜치 네이밍 규칙

작업명은 kebab-case 사용
관련 GitHub Issue 번호 필수 포함
GitHub Issue 생성 후 작업 브랜치 생성

커밋 메세지

형식:

{message}: {기능}

예시:

feat: 로그인 구현

커밋 유형	설명
feat	새로운 기능 추가 또는 기존 기능을 요구사항에 맞게 수정
fix	기능에 대한 버그 수정
docs	문서 및 주석 수정
style	코드 스타일 및 포맷팅 수정. UI 스타일링 변경은 `feat` 사용
refact	기능 변화가 없는 코드 리팩터링
test	테스트 코드 추가 및 수정
chore	패키지 매니저 수정 및 기타 설정 변경 (`.gitignore` 등)
ci/cd	빌드, 배포 및 Workflow 설정 수정
design	UI 관련 작업은 기본적으로 `feat`를 사용
comment	주석 관련 작업은 기본적으로 `docs`를 사용
rename	파일·폴더 이름 변경은 작업 목적에 맞는 Message 사용
remove	코드·파일 제거는 작업 목적에 맞는 Message 사용
BREAKING CHANGE	기존 기능과 호환되지 않는 변경 발생 시 명시
HOTFIX	배포 환경에서 긴급 수정이 필요한 경우 사용

Emoji Convention

Emoji	Message	Description
✨	feat	새로운 기능 추가, 기존 기능을 요구사항에 맞게 수정
🐛	fix	기능에 대한 버그 수정
📕	docs	문서 및 주석 수정
🎨	style	코드 스타일 및 포맷팅 수정
♻️	refact	기능 변화가 없는 코드 리팩터링
✅	test	테스트 코드 추가 및 수정
📌	chore	패키지 매니저 수정 및 기타 설정 변경
🚀	ci/cd	빌드, 배포 및 Workflow 설정 수정

Issue 컨벤션

Issue Title

형식:

[{Message}] {작업명}

예시:

[Feat] 로그인 페이지 구현

Issue 작성 규칙

.github/ISSUE_TEMPLATE/에 Issue Template 관리
- feature.md
- bug.md
Issue 제목은 정해진 Convention을 따름
Assignees 필수 설정
Labels 필수 설정
Projects 필수 설정
작업 단위가 큰 경우 하위 체크리스트로 분리

Issue Template

### 작업 내용
- 구현할 기능

### 체크리스트
- [ ] 세부 작업 1
- [ ] 세부 작업 2

### 참고 자료
- 디자인, 문서 링크

PR 컨벤션

예시:

Feature(#3): 로그인 페이지 구현

PR Title

형식:

{Message}(#{issue-number}): {작업명}

태그	의미	설명
refactor	코드 구조 개선	기능 변경 없이 코드 구조 및 가독성 개선
perf	성능 개선	렌더링, 네트워크 등 성능 관련 개선
remove	코드/파일 제거	불필요한 코드 또는 파일 제거
fix	버그 수정	기존 기능의 오류 수정
hotfix	긴급 수정	배포 후 긴급하게 수정해야 하는 문제
feature	기능 추가	새로운 기능 추가 또는 UI 기능 구현
feature	UI/스타일 수정	서비스 UI 및 스타일 구현·변경
revert	변경 사항 되돌리기	이전 변경 사항을 원래 상태로 복원
merge	브랜치 병합	브랜치 간 변경사항 병합
docs	주석 추가/수정	문서 또는 주석 관련 수정
db	DB 관련 변경	데이터 구조와 관련된 변경 사항

PR 작성 규칙

관련 Issue 번호 반드시 연결
PR 본문에 Closes #{issue-number} 작성
Merge 시 연결된 Issue 자동 Close
Reviewers 설정
Assignees 설정
Projects 연결
Labels 설정
PR 제목의 Message와 Label 통일
PR Merge는 Squash and Merge 사용
Merge 완료 후 작업 브랜치 삭제

Label 예시

Message Label:

feature
fix
refactor
docs
test
ci/cd

기능 영역 Label:

calendar🗓️
gift🎁

Pull Request Template

.github/PULL_REQUEST_TEMPLATE.md

### 구현 배경
- Closes #3
- 작업 동기

### 작업 사항
- 구현 사항
    - 세부 구현 사항

### 추가 논의
- 구현 중 발생한 이슈
- 추가로 하고 싶은 말

트러블 슈팅

1. 트러블 슈팅 제목

사용 라이브러리

라이브러리	역할 / 설명
Next.js	React 기반 프레임워크. App Router와 SSR을 기반으로 페이지 렌더링 및 라우팅 구성
React	컴포넌트 기반 사용자 인터페이스 구현
TypeScript	정적 타입 검사를 통한 컴포넌트, API 및 상태 타입 관리
Tailwind CSS	Utility Class 기반 스타일링 및 반응형 레이아웃 구성
Radix Primitives	접근성을 고려한 Headless UI Primitive 제공
TanStack Query	REST API 서버 상태 캐싱 및 동기화
Zustand	테마와 전역 UI 상태 관리
React Hook Form	폼 입력값, Validation, Error 및 Submit 상태 관리
Zod	입력값 및 API 응답 데이터 Schema 검증
openapi-fetch	OpenAPI 기반 타입 안전한 REST API 요청
`@stomp/stompjs`	STOMP over WebSocket 기반 실시간 익명 채팅
React DayPicker	달력 UI 및 날짜 선택
Firebase Cloud Messaging	Web Push 알림 수신 및 Registration Token 관리
Workbox	PWA Service Worker 구성 및 관리
Lucide React	공통 UI 아이콘
date-fns	날짜 계산 및 변환
MSW	API Mocking
Sentry	프론트엔드 런타임 오류 및 성능 모니터링

디자인 시스템

배포 환경 및 CI/CD 파이프라인

배포 환경

항목	기술
Framework	Next.js
Runtime	Node.js
Hosting	AWS Amplify Hosting
Repository	GitHub
CI/CD	GitHub Actions
Package Manager	npm

배포 원칙

main 브랜치는 항상 배포 가능한 상태 유지
main 직접 Push 금지
모든 코드 변경은 Pull Request를 통해 반영
Merge 전 필수 Status Check 통과
- lint
- build
Review 승인 후 Squash and Merge 사용

CI/CD 흐름

Issue 생성

→ 작업 브랜치 생성

→ 개발 및 Commit

→ Pull Request 생성

→ Lint 검사

→ Build 검사

→ Code Review

→ Approve

→ Squash and Merge

→ main 반영

→ AWS Amplify 배포

환경 변수 관리

환경 변수와 Secret은 Repository에 직접 Commit하지 않음
GitHub Actions Secrets 사용
AWS Amplify Environment Variables 사용
.env 파일과 Secret 값은 Git Repository에 Commit하지 않음

코드 품질 관리 도구

도구	역할	목적
도구명

테스트 전략

도구	역할	목적
도구명

Frontend Wiki - 100-hours-a-week/KTB4-4th-wiki GitHub Wiki

Need U Frontend Wiki

서비스 바로가기

목차

개발 일정

컨벤션 룰

코드 컨벤션 (Prettier & ESLint)

깃 브랜치 전략

커밋 메세지

Issue 컨벤션

PR 컨벤션

트러블 슈팅

사용 라이브러리

디자인 시스템

배포 환경 및 CI/CD 파이프라인

코드 품질 관리 도구

테스트 전략

⚠️ GitHub.com Fallback ⚠️

Frontend Wiki - 100-hours-a-week/KTB4-4th-wiki GitHub Wiki

Need U Frontend Wiki

서비스 바로가기

목차

개발 일정

컨벤션 룰

코드 컨벤션 (Prettier & ESLint)

깃 브랜치 전략

커밋 메세지

Issue 컨벤션

PR 컨벤션

트러블 슈팅

사용 라이브러리

디자인 시스템

배포 환경 및 CI/CD 파이프라인

코드 품질 관리 도구

테스트 전략

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️