이 프로젝트는 create-next-app으로 생성된 Next.js 프로젝트입니다.
- Node.js 20 이상
- npm, yarn, pnpm, 또는 bun
- 저장소를 클론하고 의존성을 설치합니다:
npm install- 환경 변수를 설정합니다:
cp .env.example .env.local
# .env.local 파일을 열어 실제 값을 입력하세요
# ⚠️ .env.local은 Git에 커밋되지 않습니다 (보안)- Git hooks를 초기화합니다:
npm run prepare- 개발 서버를 실행합니다:
npm run dev
# 또는
yarn dev
# 또는
pnpm dev
# 또는
bun dev브라우저에서 http://localhost:3000을 열어 결과를 확인하세요.
참고: 현 개발 환경에서는 Turbopack이 포트 바인딩을 시도하다가 종료되기 때문에
npm run dev와npm run build모두--webpack플래그를 강제로 사용하도록 설정했습니다.
app/page.tsx 파일을 수정하여 페이지를 편집할 수 있습니다. 파일을 편집하면 페이지가 자동으로 업데이트됩니다.
- Framework: Next.js 16.1.1
- Language: TypeScript 5
- UI Library: React 19.2.3
- Styling: Tailwind CSS 4
- Code Quality: ESLint, Prettier
- Git Hooks: Husky, lint-staged, Commitlint
app/
(app)/
layout.tsx # 공용 내비게이션/테마 헤더
page.tsx # / -> /dashboard 리디렉션
dashboard/ # 대시보드 RSC 페이지
learning-resources/ # 자료실 페이지
(auth)/
layout.tsx # 로그인/회원가입 전용 레이아웃
login/
register/
src/
components/ # 공용 UI, 레이아웃, providers
features/ # 도메인 단위 UI/데이터 (dashboard, auth 등)
lib/ # fonts, utils 등 헬퍼
npm run dev- 개발 서버 실행npm run build- 프로덕션 빌드npm run start- 프로덕션 서버 실행npm run lint- ESLint 실행npm run lint:fix- ESLint 오류 자동 수정npm run format- Prettier로 코드 포맷팅npm run format:check- 코드 포맷 검사npm run type-check- TypeScript 타입 검사npm test- Jest 테스트 실행
이 프로젝트는 코드 품질과 포맷팅을 위해 ESLint와 Prettier를 사용합니다. Husky와 lint-staged 덕분에 각 커밋 전에 코드가 자동으로 포맷팅되고 린트됩니다.
이 프로젝트는 Husky를 사용해 Git 커밋 훅을 관리합니다.
의존성 설치 후 npm run prepare 스크립트를 통해 Husky 훅이 설정됩니다.
- 커밋 시 커밋 메시지 규칙을 검사합니다 (commitlint)
- 훅 설정은
.husky/디렉토리에 위치합니다
VS Code를 사용하는 경우, 프로젝트에는 다음을 제공하는 권장 확장 프로그램과 설정이 포함되어 있습니다:
- 저장 시 자동 포맷팅
- 실시간 ESLint 오류 표시
- TypeScript IntelliSense 제공
npm run format # 모든 파일 포맷팅
npm run lint:fix # 린트 오류 수정이 프로젝트는 Conventional Commits 규격을 따릅니다:
<type>: <subject>
타입:
feat: 새로운 기능 추가fix: 버그 수정docs: 문서 변경style: 코드 스타일 변경 (포맷팅 등)refactor: 코드 리팩토링test: 테스트 추가 또는 변경chore: 빌드 작업, 패키지 매니저 설정
예시:
feat: 사용자 인증 기능 추가fix: 다크모드 토글 문제 해결docs: README 업데이트
각 커밋 전에:
- Staged된 파일이 자동으로 린트 및 포맷팅됩니다
- 커밋 메시지가 conventional commits 형식에 맞는지 검증됩니다
커밋이 실패하면 오류를 수정하고 다시 커밋하세요.
.env.example파일을.env.local로 복사합니다:
cp .env.example .env.local-
.env.local파일을 열어 실제 값을 입력합니다. -
⚠️ 중요:.env.local은 Git에 커밋되지 않습니다 (보안).
- 공개 변수 (브라우저에서 접근 가능):
NEXT_PUBLIC_접두사 사용 - 비공개 변수 (서버에서만 접근 가능): 접두사 없음
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000이 프런트엔드 레포에서는 로컬 개발 시 .env.local만 사용합니다.
.env.local(로컬 개발용, Git에 커밋되지 않음)
배포 환경(AWS 등)에서는 플랫폼의 환경 변수 설정을 사용합니다.
이 프로젝트는 지속적 통합을 위해 GitHub Actions를 사용합니다. main 또는 develop 브랜치에 푸시하거나 Pull Request를 열 때마다 다음 검사가 자동으로 실행됩니다:
- ESLint 검사
- Prettier 포맷 검증
- TypeScript 타입 검사
- 프로덕션 빌드 테스트
이 프로젝트는 Vercel이 아닌 AWS 환경에 배포합니다. • Frontend (Next.js): AWS에 배포 (SSR/Node 런타임 필요) • Backend (Express): 별도 저장소/서비스로 AWS에 배포 • 통신 방식: Front → Back API 호출 (도메인/환경변수로 분리)