프론트엔드 개발 표준 및 구조 설계 - 100-hours-a-week/5-yeosa-wiki GitHub Wiki

1. 폴더 구조

  • React/Vite 기본 구조에서 확장
  • 페이지, 도메인 단위로 분류

src/
├── App.tsx             #리액트 라우터
├── App.css
├── index.css
├── main.tsx
├── vite-env.d.ts
├── api/                #도메인 별 API
│   ├── albums/           #앨범
│   ├── notification/     #알림
│   ├── pictures/         #사진
│   ├── user/             #사용자 관련 데이터 조회
│   ├── auth/             #로그인 및 인증
│   ├── config.js         #상수 관리
│   └── apiClient.js      #api Helper
├── assets/             #아이콘, 기본 이미지, 로고 등
│   ├── icons/            #아이콘
├── components/         #페이지 별 컴포넌트 분류
│   ├── Album/            #앨범페이지 하위 컴포넌트
│   ├── AlbumEditor/      #앨범에디터 하위 컴포넌트
│   ├── Main/             #메인페이지 하위 컴포넌트
│   ├── MyPage/           #마이페이지 하위 컴포넌트
│   └── common/           #공용 컴포넌트
├── hooks/           
├── pages/              #페이지 컴포넌트
│   └── auth/             #Ouath 콜백 페이지
├── services/
├── stores/


├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
├── index.html
├── eslint.config.js
└── ...

2. Git 브랜칭 전략

2.1 팀 브랜칭 전략

  • main : Production에 배포되는 브랜치
  • dev : Develope 및 Test 브랜치
  • feature

    • 이슈종류에 따라 브랜치 경로 생성 후 작업

      • 브랜치명 컨벤션: feature/{이슈 번호}

    • Pull Request (PR) 생성 후 Rebase Merge.

      • PR 리뷰와 승인 필요
  • fix : 동일
  • !HOTFIX
    • 급한 이슈 발생 시 해당 브랜치 이용
    • 브랜치명 컨벤션 : !HOTFIX/{이슈 번호}

이슈 종류

Issue Name Description
Bug: Critical 심각한 버그를 리포트
Bug: Minor 작동하지만 기대와 다른 경우 리포트
BugFix 버그 수정
Chore 빌드/환경 관련 작업
Deploy 배포 관련 작업
Duplicate 중복된 이슈
Feature 새로운 기능 개발
Refactor 코드 리팩토링
Test 테스트 관련 작업

2.2 브랜치 흐름

# 기능 개발 시
feature/* -> dev -> main

# 급한 오류 해결
hotfix -> dev -> main

2.3 Commit Convention

<Type>: <Commit Title>

Types 설명
feat 새로운 기능 추가
fix 버그 수정
design CSS 등 사용자 UI 디자인 변경
!BREAKING CHANGE 커다란 API 변경의 경우
!HOTFIX 치명적인 버그로 인한 긴급한 수정
style 코드 포맷 변경, 세미콜론 누락 등 (코드 수정은 없는 경우)
refactor 프로덕션 코드 리팩토링
comment 필요한 주석 추가 및 변경
docs 문서 수정
test 테스트 추가, 테스트 리팩토링 (프로덕션 코드 변경 X)
setting 패키지 설치, 개발 설정 관련 변경
chore 빌드, 테스트 업데이트, 패키지 매니저 설정 (프로덕션 코드 변경 X)
rename 파일 혹은 폴더명을 수정하거나 옮기는 작업
remove 파일을 삭제하는 작업만 수행한 경우

3. 네이밍 컨벤션

3.1 파일, 폴더 컨벤션

폴더명

  • 소문자, camelCase 사용

파일명

  • 라우팅 파일은 next.js의 기본 설정인 page.tsx, layout.tsx로 설정합니다.
  • 컴포넌트 파일 : PascalCase
  • 기타 파일 : camelCase
    • 커스텀 훅 파일 : use 접두사 사용

3.2 컴포넌트 기본 형식

const Component =({props}) => {

	return (
		<>
			{/* 컴포넌트 내용 */}
		</>
	);
}

export default Component;

3.3 식별자 컨벤션

변수 및 함수

  • camelCase
  • boolean 변수는 is, has, should 접두사 사용

상수

  • SCREAMING_SNAKE_CASE 사용

4. 코드 컨벤션

4.1 Import

// 1. React 관련
import React from 'react';
import { useState, useEffect } from 'react';

// 2. 내부 컴포넌트
import Button from '@/components/ui/Button';

// 3. 커스텀 훅 & 서비스
import { useAuth } from '@/hooks/use-auth';

// 4. 외부 라이브러리
import axios from 'axios';
import exifr from 'exifr';

// 5. assets

4.2 함수형 컴포넌트 내부 순서

const Component = ({ prop1, prop2 }) => {
  // 1. 상태 관리
  const [state, setState] = useState();
  
  // 2. 커스텀 훅
  const { data, loading } = useCustomHook();
  
  // 3. 이벤트 핸들러
  const handleClick = () => {
    // 핸들러 로직
  };
  
  // 4. useEffect
  useEffect(() => {
    // 부수 효과
  }, []);
  
  // 5. 조건부 렌더링
  if (loading) return <Loading />;
  
  // 6. JSX 반환
  return (
    <div>
      {/* 컴포넌트 내용 */}
    </div>
  );
};

4.3 주석 작성 규칙

/**
 * 사용자 프로필을 표시하는 컴포넌트
 * @param user - 사용자 정보 객체
 * @param onEdit - 편집 버튼 클릭 시 호출되는 함수
 */
const UserProfile = ({ user, onEdit }: UserProfileProps) => {
  // TODO: 프로필 이미지 업로드 기능 추가
  
  return (
    <div>
      {/* 사용자 아바타 영역 */}
      <Avatar src={user.avatar} />
    </div>
  );
};

4.4 Tailwind Convention

  • ESLint 플러그인 eslint-plugin-tailwindcss에 따른 자동 정렬 사용

4.5 Linting 컨벤션

  • Vite 프로젝트 생성 시 초기 설정을 확장

  • Import (simple-import-sort ) 사용

  • "no-unused-vars": "on" 설정

  • 예시 코드 (추후 변경 예정)

5. 반응형 디자인 지원 전략

  • 모바일 브라우져 기준으로 개발
  • 기본 개발 화면 크기
    • Width : 392px
    • Height : 790px
  • 기본 넓이 보다 커지는 경우 중앙에 배치한다.
  • 기본 길이보다 커지는 경우 확장된다.
  • 적응형 디자인을 일부 적용한다. (넓이값을 높이에 사용)

추가로 설정이 필요한 경우에는 다음과 같이 package.json 에 BrowserList를 적는 방법으로 명시합니다.

{
  "browserslist": [
    "chrome 64",
    "edge 79",
    "firefox 67",
    "opera 51",
    "safari 12"
  ]
}
⚠️ **GitHub.com Fallback** ⚠️