서버 컴포넌트를 사용한 Next.js 15 블로그 개발 경험

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

Next.js 15 및 서버 컴포넌트를 사용하는 개발자, 특히 정적 사이트 생성 및 인증 처리에 어려움을 겪는 중급 이상 개발자

핵심 요약

• 서버 컴포넌트는 정적 빌드 시 내부 API 호출이 불가능 → 데이터베이스 직접 조회가 필수
• 세션 정보는 fetch() 시 자동으로 전송되지 않음 → next/headers의 cookies() 사용하여 수동 전달 필요
• AI 의존보다 공식 문서 확인이 실무에서 더 효과적 → cookies().toString() 활용 권장

섹션별 세부 요약

1. 정적 페이지에서 API 호출 실패 원인

• 로컬 개발 환경에서는 Node 서버가 항상 실행되지만, 빌드 시 서버가 실행되지 않음
• 내부 API 라우트가 아직 구동되지 않았기 때문에 데이터 로드 실패
• 해결책: 서버 컴포넌트에서 데이터베이스를 직접 조회

2. 동적 라우트에서의 API 호출 성공

• 동적 페이지에서는 사용자가 방문할 때 API 호출이 가능
• 서버가 요청을 처리하고 전체 페이지를 반환
• 정적 빌드와 동적 라우트의 차이점 명확히 이해 필요

3. 세션 인증 실패 문제

• API 라우트 내 세션 정보가 null로 반환되는 문제 발생
• AI 도움 요청 실패 후 공식 문서 참고 → fetch() 시 쿠키 수동 전달 필요
• NextAuth.js + JWT 인증 시 쿠키 기반 세션 관리

4. `cookies()` 메서드 활용 방법

• next/headers 모듈의 cookies() 사용
• 쿠키 문자열 생성: cookieStore.getAll().map().join()
• 공식 문서 cookies().toString() 사용 권장

5. 실무 적용 팁

• 서버 컴포넌트는 항상 서버에서 실행되므로, 정적 빌드 시 데이터베이스 직접 조회 필요
• 인증 로직은 fetch() 시 쿠키 수동 전달으로 처리
• AI 답변보다 공식 문서 확인이 더 신뢰성 있음

결론

• 서버 컴포넌트는 강력하지만, 정적 빌드, 인증, 쿠키 전달 등 여러 GOTCHA 존재
• use client보다 서버 컴포넌트를 기본으로 사용하고, 인터랙티브 요소만 클라이언트 컴포넌트로 분리
• Composition 패턴 적용하여 컴포넌트 구성 유연성 확보
• 실무에서는 문서 확인과 실전 경험을 통해 문제 해결 능력 향상 필수