4단계. 프론트엔드 개발 표준 및 구조 설계 - 100-hours-a-week/KTB4-1st-wiki GitHub Wiki
폴더 구조
참고한 페이지 : https://gamza1013.tistory.com/114
project/
├── src/
│ ├── app/
│ │ ├── layout.tsx # 최상위 레이아웃
│ │ │
│ │ ├── pages/ # 일반 사용자 페이지 그룹
│ │ │ ├── layout.tsx # Navbar, Modal, AIChatbot 배치
│ │ │ ├── page.tsx # /
│ │ │ ├── about/
│ │ │ │ └── page.tsx # /about
│ │ │ ├── items/
│ │ │ │ └── page.tsx # /items
│ │ │ ├── me/
│ │ │ │ └── page.tsx # /me
│ │ │ ├── groups/
│ │ │ │ └── page.tsx # /groups
│ │ │ ├── exchange/
│ │ │ │ └── page.tsx # /exchange
│ │ │ ├── chat/
│ │ │ │ └── page.tsx # /chat
│ │ │ ├── report/
│ │ │ │ └── page.tsx # /report
│ │ │ └── contactus/
│ │ │ └── page.tsx # /contactus
│ │ │
│ │ ├── auth/
│ │ │ ├── layout.tsx # 로그인 전용 레이아웃
│ │ │ └── login/
│ │ │ └── page.tsx # /login
│ │ │
│ │ └── admin/
│ │ ├── layout.tsx # 관리자 전용 레이아웃
│ │ ├── report/
│ │ │ └── page.tsx # /admin/report
│ │ ├── contactus/
│ │ │ └── page.tsx # /admin/contactus
│ │ └── me/
│ │ └── page.tsx # /admin/me
│ │
│ ├── components/
│ │ ├── layout/
│ │ │ ├── navbar/
│ │ │ ├── modal/
│ │ │ └── ai-chatbot/
│ │ └── common/ # 기타 공통 컴포넌트
│ │
│ ├── store/ # Zustand 전역 상태
│ │ ├── auth/
│ │ ├── modal/
│ │ └── ai-chatbot/
│ │
│ ├── hooks/
│ ├── utils/
│ └── types/
│
├── public/
│ ├── images/
│ └── icons/
│
├── tests/
│ ├── pages/
│ ├── components/
│ └── store/
│
├── next.config.ts
├── tsconfig.json
├── package.json
└── node_modules/
반응형 디자인 지원 전략
지원 범위 (브라우저 호환성)
참고한 페이지 : https://nextjs.org/docs/architecture/supported-browsers
- 데스크톱
- 태블릿
- 모바일
브라우저 호환성 - Next.js 공식 문서 기준 브라우저별 최소 지원 버전
- Chrome 111+
- Edge 111+
- Firefox 111+
- Safari 16.4+
테스트 환경 - 현재 팀 내 있는 기종
macOS: Chrome 153 (macbook Pro)
iOS: Safari (iPhone 15, iPhone 16 Pro)
Android : Chrome (Galaxy s25+, Galaxy 26 Ultra)
브레이크포인트 (개발 시 변동 가능)
직접 Chrome 기준 브라우저 개발자 도구 꺼내서 측정하면서 판단
- 모바일:
0~679px- 태블릿:
680~1023px- 데스크톱:
1024px 이상
코드 컨벤션
참고한 페이지 : https://github.com/airbnb/javascript
Next.js에서 정해진 파일명 → 그대로 사용
| 용도 | 파일명 |
|---|---|
| 페이지 | page.tsx |
| 공통 레이아웃 | layout.tsx |
| 로딩 화면 | loading.tsx |
| 오류 화면 | error.tsx |
컨벤션
- 파일·폴더:
kebab-case - React 컴포넌트·타입:
PascalCase - 함수·변수·훅:
camelCase- boolean은 is/has/can 등을 앞에 사용
- 환경변수·전역 상수:
UPPER_SNAKE_CASE
Lint(Formatting)
Lint : 코드의 오류 가능성 또는 규칙 위반을 탐지
Formatting : 코드의 모양을 일정하게 정리
- ESLint + Prettier 적용, Semantic Release 적용
- ESLint는 코드 실행 전 오류 가능성/잘못된 패턴/팀 규칙 위반 등을 발견하여 알려주어 오류 방지가 가능하다. 만약 사용하지 않는다면 런타임에서 예기치못한 오류를 발생시키거나 팀 규칙에 맞지않는 코드를 작성하게 되어 전반적인 코드 품질이 떨어질 수 있다.
- Prettier는 들여쓰기, 줄바꿈 등 코드의 모양을 자동적으로 통일해준다. 사용하지 않게 되면 개발자마다 코드를 작성하는 방법이 달라 전체적인 코드의 일관성이 달라지게 된다.
→ 사용함으로써 풍부한 플러그인 지원 생태계를 활용할 수 있고, 사소한 오류도 일찍 발견할 수 있다. 자동화된 규칙이 있으니 로직에만 집중할 수도 있고, 전반적으로 통일된 하나의 코드를 만들 수 있다.
Polyfill 전략
Polyfill : 기본적으로 지원하지 않는 이전 브라우저에서 최신 기능을 제공하는데 필요한 코드. 참고한 페이지 : https://toss.tech/article/smart-polyfills
https://ko.javascript.info/polyfills
https://gs.statcounter.com/browser-version-market-share/all/south-korea
- 현재 지원할 브라우저는 macOS chrome 111+, iOS Safari 16.4+, Android Chrome 111+이다. https://github.com/zloirock/core-jsIE는 지원하지 않을 예정이며, 만약 지원되지 않는 브라우저에서 접근 시 진입 코드에서 업데이트 또는 다른 브라우저 사용을 안내하는 화면을 보여줄 예정.
- 당장 사용하지 않는 이유로는 더 이상 인터넷 익스플로러를 쓰지 않기 때문에 폴리필의 중요도가 급히 떨어졌기 때문이다. 추후 개발을 진행하면서 실제로 사용하는 기능 중 구형 브라우저에 지원되지 않는 기능들만 선택적으로 골라서 폴리필을 적용할 것.
SEO
- 로그인 화면에 SEO 적용
- 추후 그룹 검색과 물품 관련해서 공개하도록 확장 가능
테스트
- 단위 테스트 : 계산/검증/데이터 변환
Vitest사용- E2E 테스트와 컴포넌트 테스트로 사용할 Playwright 같은 경우, 단위테스트를 지원하기는 하지만 모듈 모킹 기능이 부족하다. Playwright는 주로 모킹하는 부분이 HTTP나 웹소켓 등 브라우저 외부 통신을 지원하지만 단위테스트에서 필요한 모킹은 함수/클래스/모듈이다. 따라서, 현재 사용하는 빌드도구인 Vite 기반으로 동작하는 Vitest를 활용하기로 결정하게 되었다. Vitest는 Vite의 설정과 코드 변환 파이프라인을 공유하고, 단위 테스트용 mocking을 지원한다.
- 컴포넌트 테스트 : 주요 컴포넌트의 사용자 상호작용
Playwright사용- E2E 테스트를 지원하는 Playwright에서 컴포넌트 테스트도 지원하기 때문에 이미 사용하는 것을 활용할 생각이다. 추가적인 라이브러리 다운로드는 필요 없지만 Playwright 내부 추가 설정은 필요. (Story Gallery 설정)
- E2E 테스트 : 핵심 사용자 흐름
Playwright사용- 후보군으로는 Cypress를 고려했다. Cypress와 Playwright 둘 다 프론트엔드 E2E 테스트로 사용하기 좋지만, Cypress는 하나의 테스트에서 두개의 독립된 브라우저를 동시에 관리하지 못한다는 특징을 갖고 있다. 구현하려는 서비스 특성상 알림이 오고, 채팅을 주고 받는 등 두 명 이상의 사용자가 서로 인터렉팅하는 액션이 많은데, 그런 부분들은 Cypress에서 테스트로 작성하기가 어렵기 때문에 해당 구현이 가능한 Playwright를 고르게 되었다.