Frontend

React 네이밍 컨벤션 & Git/PR 규칙 정리

2025년 10월 19일 · 6분 읽기

React 개발에서 함수와 컴포넌트 네이밍은 단순한 스타일 문제가 아닙니다. 가독성, 유지보수성, 협업 효율을 결정짓는 핵심 요소입니다. 이 글에서는 기본 개념부터, 기업 현장에서 쓰이는 규칙, 그리고 제가 실제로 사용하는 Git/PR/파일 네이밍 규칙까지 한 번에 정리했습니다.

1️⃣ 왜 네이밍 규칙이 중요한가?

이름이 모호해 디버깅이 어려움
상태나 함수를 찾느라 시간 낭비
컴포넌트와 파일명이 뒤엉켜 협업 시 혼란 발생

→ 초기부터 좋은 네이밍 습관을 들이는 것이 중요합니다.

2️⃣ 기본 React 네이밍 규칙

✔️ 컴포넌트

파일명 = 컴포넌트명 (PascalCase)

PostList.jsx → function PostList()
CommentForm.jsx → function CommentForm()

✔️ 이벤트 핸들러

on + 동작명 + Handler 또는 handle + 동작명

onClick → handleClick()
onSubmit → handleSubmit()

✔️ 상태 변수

상태 값: entered + 데이터명
상태 변경 함수: set + 상태명
Boolean 값은 is, has 접두사 사용 → 예: isLoading, hasPermission

✔️ 커스텀 훅 & 컨텍스트

훅: use로 시작 (useAuth, useFetch)
컨텍스트: xxxContext, 프로바이더: xxxProvider

3️⃣ 실제 기업 관례

✔️ 핸들러

스타트업/중소기업: handleClick, handleChange (간결함 우선)
대기업/프레임워크 팀: onClickHandler (이벤트 리스너 느낌 강조)

✔️ 상태 변수

Boolean: is, has 접두사 (isModalOpen, hasError)
데이터 값: xxxData (userData, postData)
로딩 상태: isLoading, isSubmitting

✔️ CSS/스타일 컴포넌트

Container, Wrapper, Box 접미사 사용 → PostCardContainer, CommentBox

✔️ 유틸 함수

camelCase 사용 (formatDate, capitalizeText)

✔️ 테스트 파일

컴포넌트명 + .test.js 또는 .spec.js

PostList.test.js

4️⃣ React 공식 문서 요약

컴포넌트 이름은 대문자로 시작 (JSX 태그 구분)
커스텀 훅 이름은 use로 시작

5️⃣ 팀에서 네이밍 규칙 정하기

킥오프 단계에서 컨벤션 문서 작성 (Notion, Google Docs)
ESLint, Prettier 같은 자동화 툴로 강제 적용
eslint-plugin-react에서 PascalCase 강제 가능

📂 Git / PR / 파일 네이밍 규칙 (실제 사용)

<table style="color: #333333; text-align: start; border-collapse: collapse; width: 100%;" border="1" data-ke-align="alignLeft"><tbody><tr><td style="text-align: left;">feature</td><td style="text-align: left;">새로운 기능 개발</td></tr><tr><td style="text-align: left;">bugfix</td><td style="text-align: left;">버그 수정</td></tr><tr><td style="text-align: left;">docs</td><td style="text-align: left;">문서 수정</td></tr><tr><td style="text-align: left;">config</td><td style="text-align: left;">설정 파일 수정</td></tr></tbody></table>

feature/25-ui-component
docs/update-readme
style/update-button

2) File Naming Rule

항목규칙예시

<table style="color: #333333; text-align: start; border-collapse: collapse; width: 100%;" border="1" data-ke-align="alignLeft"><tbody><tr><td style="text-align: left;">컴포넌트 파일</td><td style="text-align: left;">PascalCase</td><td style="text-align: left;">Button.tsx, UserCard.tsx</td></tr><tr><td style="text-align: left;">유틸 함수</td><td style="text-align: left;">camelCase</td><td style="text-align: left;">formatDate.ts, apiCall.ts</td></tr><tr><td style="text-align: left;">폴더 이름</td><td style="text-align: left;">kebab-case</td><td style="text-align: left;">user-profile/, auth/</td></tr><tr><td style="text-align: left;">스타일 파일</td><td style="text-align: left;">kebab-case</td><td style="text-align: left;">header-style.scss</td></tr></tbody></table>

3) Pull Request Rule

PR 제목 형식: [prefix] 작업 요약
PR 대상 브랜치: develop 또는 main

[feat] 새로운 버튼 컴포넌트 추가
[fix] 드롭다운 버그 수정
[docs] README 업데이트

7️⃣ 네이밍 아이디어 참고 사이트

GitHub 계정으로 댓글을 남길 수 있어요.