Expo2026-Front

---

📔 2026_EXPO의 프론트엔드 저장소입니다.

React, TypeScript, Vite를 기반으로 하며, 유지보수성을 위해 기능 단위(Feature-based) 아키텍처를 따릅니다.

🛠 Tech Stack

분류	기술	비고
Core		UI 라이브러리 및 언어
Build		빌드 도구 및 개발 서버
State	TanStack Query (Server), Zustand (Client)	서버/클라이언트 상태 관리 분리
Network	Axios	HTTP 비동기 통신 라이브러리
Style		CSS
Routing	React Router DOM	SPA 라우팅
Date	React Day Picker	캘린더/날짜 선택 UI
Icons	lucide-react	아이콘 라이브러리
Pkg Mgr	npm	패키지 매니저
Quality	ESLint, Prettier	코드 품질 및 포맷팅 (수동 실행)

Getting Started (설치 및 실행)

이 프로젝트는 Node.js v20 (LTS) 이상 환경을 권장합니다.

node -v

1. 프로젝트 클론

git clone git@github.com:el-dmu/Expo2026-Front.git
cd 파일이름 아직 미정입니다.

2. 패키지 설치

npm install

Tip: 팀원들과 정확히 동일한 버전을 설치하려면 npm ci 명령어를 사용하는 것이 좋습니다.

3. 환경 변수 설정 (.env)

루트 디렉토리에 .env 파일을 생성하고, 팀 노션(Notion)에 공유된 키 값을 입력하세요.

(예시)

VITE_API_BASE_URL=http://localhost:8080/api/v1
VITE_SOCKET_URL=http://localhost:8080

4. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:5173으로 접속하여 확인합니다.

5. 프로덕션 빌드 확인 (선택)

npm run build
npm run preview

📂 Project Structure (폴더 구조)

우리는 기능(Feature) 중심의 아키텍처를 사용합니다. 관련된 로직(UI, Hook, API)이 하나의 폴더에 모여 있어야 유지보수가 쉽습니다.

src/
├── assets/              # 이미지, 폰트 등 정적 리소스
├── components/          # 전역 공용 UI / 레이아웃

개발 원칙

1. Colocation: 특정 기능에서만 쓰이는 컴포넌트는 features/기능명/components 안에 둡니다.
2. Barrel Exports: index.ts를 활용하여 import 경로를 깔끔하게 유지합니다.
3. Absolute Import: ../../ 대신 @/features/user 와 같이 절대 경로(@)를 사용합니다.

Contribution Guide (협업 규칙)

1. Git Flow 및 브랜치 전략

• main: 배포 가능한 안정 버전
• develop: 개발 중인 코드 (PR 대상)

📌 브랜치 명명 규칙: 타입/기능명_작성자 누가 작업 중인지 명확히 알기 위해 기능명 뒤에 작성자 이름을 붙입니다.

타입	설명	사용 예시
feat	새로운 기능 추가	feat/login_Minsik(본인 이름)
fix	버그 수정	fix/home-error_Minsik(본인 이름)
design	CSS 등 스타일 변경	design/main-color_Minsik(본인 이름)
refactor	코드 리팩토링	refactor/api-logic_Minsik(본인 이름)
docs	문서 수정	docs/readme_Minsik(본인 이름)

2. Commit Convention

커밋 메시지는 Conventional Commits 규칙을 따릅니다.

• feat: 로그인 페이지 퍼블리싱
• fix: 매칭 필터링 오류 수정
• docs: 리드미 수정

3. Code Quality (PR 전 필독!)

우리는 코드 품질을 유지하기 위해 PR(Pull Request)을 올리기 전, 로컬에서 자가 검사를 수행해야 합니다.

✅ PR 전 실행 명령어 작업을 마치고 원격 저장소에 올리기 전, 터미널에 아래 명령어들을 입력하여 에러가 없는지 확인합니다.

명령어	역할	설명
npm run type-check	타입 검사	TypeScript 문법 오류나 타입 불일치를 잡아냅니다. (컴파일은 하지 않음)
npm run lint	스타일 검사	ESLint 규칙(미사용 변수, 컨벤션 등) 위반 사항을 확인합니다.

# 실행 예시
npm run type-check && npm run lint

⚠️ Troubleshooting

Q. npm install 시 에러가 발생해요.
A. Node 버전이 맞는지 확인하세요. (node -v >= 20). nvm use 20을 권장합니다. 캐시 문제라면 npm cache clean --force 후 다시 시도해 보세요.

Q. import 경로에서 @/가 인식이 안 돼요.
A. VS Code를 재시작하거나 Ctrl + Shift + P (Win) / Cmd + Shift + P (Mac) 를 눌러 명령 팔레트를 열고 TypeScript: Restart TS server를 실행해 보세요.

---