frontend/docs/debugfrontend.md

프론트엔드 디버깅 환경 구축 및 Windsurf 디버깅 가이드

이 문서는 본 프로젝트(Next.js 기반 프론트엔드)에서 Windsurf 및 브라우저/VSCode를 활용해 효율적으로 디버깅하는 방법을 안내합니다.

---

1. 개발 환경 준비

1) Node.js 및 패키지 설치

• Node.js 18.x 이상 필요
• 루트 디렉토리에서:

  npm install
  # 또는
  pnpm install
  

2) 환경 변수 파일 준비

• .env.local 등 환경 변수 파일을 복사/생성합니다.
• API 엔드포인트 등 민감 정보는 환경 변수로 관리하세요.

3) Next.js 개발 서버 실행

• 아래 명령어로 개발 서버 실행:

  npm run dev
  # 또는
  pnpm dev
  

• 기본 포트: 3000 (필요시 .env 또는 package.json에서 변경)

---

2. Windsurf 디버깅 환경 구축

1) 소스맵 활성화

• Next.js는 개발 모드에서 자동으로 소스맵을 제공합니다.
• 별도 설정 없이 브라우저에서 TypeScript/JSX 소스 디버깅 가능.

2) 브라우저 디버깅

• Chrome/Edge 등에서 F12 → Sources 탭에서 실제 소스 파일에 브레이크포인트 설정.
• step-by-step 실행, 변수 값 확인, 콜스택 추적 가능.

3) VSCode 디버깅 (선택)

• .vscode/launch.json 파일 생성:

  {
    "version": "0.2.0",
    "configurations": [
      {
        "type": "chrome",
        "request": "launch",
        "name": "Next.js: Chrome 브라우저에서 디버깅",
        "url": "http://localhost:3000",
        "webRoot": "${workspaceFolder}"
      }
    ]
  }
  

• VSCode에서 디버깅 세션 시작 → 브레이크포인트, 변수 추적 가능.

4) Windsurf 연동

• Windsurf에서 “로컬 서버 연결” 기능으로 http://localhost:3000 접속.
• 브라우저 프리뷰, 콘솔 로그, 네트워크 요청, 소스맵 기반 디버깅 가능.
• "디버깅 세션 시작" 버튼 클릭 시 브라우저 개발자 도구와 동일하게 동작.

---

3. 디버깅 팁

• 핫 리로드: 코드 수정 시 자동 반영.
• React DevTools: 컴포넌트 상태, props, hooks 실시간 확인.
• 네트워크 탭: API 요청/응답 실시간 확인.
• 에러 오버레이: Next.js가 런타임/빌드 에러를 화면에 표시.

---

4. 문제 해결 체크리스트

• 빌드/런타임 에러: 터미널과 브라우저 메시지 확인.
• API 통신 문제: 네트워크 탭에서 요청/응답 확인, 환경 변수 및 서버 상태 점검.
• 소스맵 미작동: next.config.js 등에서 소스맵 관련 옵션 확인.

---

5. Windsurf 디버깅 절차 요약

1. 의존성 설치 및 개발 서버 실행 (npm run dev)
2. Windsurf에서 “로컬 서버 연결”로 http://localhost:3000 접속
3. 브라우저 프리뷰에서 UI/네트워크/콘솔/소스 디버깅
4. 필요시 VSCode에서 브레이크포인트 디버깅 병행

---

참고

• Next.js 공식문서: https://nextjs.org/docs
• Windsurf 공식문서 및 지원 채널 참고