Next.js 15 + React 19 프론트엔드와 지도 UI — 채용 플랫폼 (3)

Next.js 15·React 19·Tailwind 4와 TanStack Query로 서버 상태를 일원화하고, 쿼리 클라이언트를 서버는 격리·브라우저는 싱글턴으로 분리한 설계를 다룬다. 401 단일 비행 토큰 갱신으로 동시 만료를 한 번만 처리하고, 퍼센트 좌표 데이터로 그린 섬 지도형 탐색 UI와 조회표 라우팅까지 정리한 채용 플랫폼 프론트엔드 기록이다.

Next.js 15 + React 19 프론트엔드와 지도 UI 구현을 정리한다.

 

3편: 프론트엔드

1편 인증, 2편 이력서 백엔드에 이어, 이번엔 사용자가 직접 보는 프론트엔드다. 백엔드 API를 소비해 채용 플랫폼의 화면을 만든다.

기술 스택 (프론트엔드)

• 프레임워크: Next.js 15.3.5 (App Router)
• UI 라이브러리: React 19
• 언어: TypeScript 5
• 스타일: Tailwind CSS 4
• 데이터 페칭: TanStack React Query

최신 버전 조합(Next 15 / React 19 / Tailwind 4)으로 갔다. 새 버전은 좋지만 생태계 호환성 이슈가 따라오기도 해서, 안정적으로 묶는 데 신경 썼다.

데이터 페칭: TanStack React Query

채용 플랫폼은 "서버 상태"가 화면의 대부분이다. 공고 목록, 이력서, 지원 내역, 기업 정보 — 전부 백엔드(2편의 API)에서 온다. 이걸 useState + useEffect로 직접 다루면 로딩·에러·캐싱·재요청이 금방 지저분해진다.

그래서 서버 상태는 React Query로 일원화했다. 캐싱·로딩/에러 상태·무효화(invalidation)를 선언적으로 다룬다.

function useResumes() {
  return useQuery({
    queryKey: ['resumes'],
    queryFn: () => api.get('/resume').then((r) => r.data),
    staleTime: 60_000,
  });
}

// 이력서 작성 후, 목록 캐시 무효화 → 자동 갱신
const { mutate } = useMutation({
  mutationFn: (body) => api.post('/resume', body),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['resumes'] }),
});

"서버 상태는 React Query, 화면 로컬 상태만 useState"라는 경계를 그으니, 데이터 흐름이 예측 가능해졌다.

핵심 화면: 지도 UI

이 플랫폼에서 가장 공들인 화면이 지도 UI였다. 위치 기반으로 채용 정보를 지도 위에 보여준다. 지도는 프론트엔드에서 다루기 까다로운 축에 든다.

• 마커 표시: 데이터(좌표)를 지도 위 마커로. 데이터가 많으면 성능 이슈.
• 반응형: 데스크톱/모바일에서 지도 영역과 목록의 배치가 달라야 한다.
• 이미지·표시 동기화: 지도 위 정보와 목록/카드의 데이터가 일치해야 한다.

지도 UI를 여러 번 개선하며(마커, 표시 방식, 이미지 동기화) 다듬었다. 지도는 "한 번에 완성"이 아니라 실제 데이터를 얹어보며 반복 개선이 필요한 화면이었다.

메인 페이지와 부가 기능

메인 페이지를 만들고, 기업 자유게시판을 통합하고, 로그인 UI를 다듬었다. 실명 표시, 리다이렉트 처리 같은 잔 기능도 정리했다. 프론트엔드는 화려한 기능 하나보다, 이런 잔 기능들의 매끄러움이 완성도를 만든다.

프론트-백엔드 정렬

마지막으로 프론트엔드와 백엔드를 맞추는 작업을 했다. 2편에서 백엔드 엔티티-DB 스키마를 정렬했듯, 프론트엔드가 기대하는 데이터 모양과 백엔드가 주는 모양을 일치시켰다. 이 "경계의 정렬"은 풀스택 프로젝트에서 늘 마지막에 가장 많은 버그가 나오는 지점이다(다른 글의 채점 플랫폼에서도 같은 교훈을 겪었다).

정리하며

• 서버 상태는 React Query로 일원화 — 캐싱·로딩·무효화를 선언적으로.
• 지도 UI는 반복 개선 — 실제 데이터를 얹어보며 다듬는 화면.
• 프론트-백 정렬이 풀스택의 마지막 관문 — 데이터 모양을 양쪽이 똑같이.

다음 마지막 4편에서는 이 플랫폼에 지능을 더한 AI 오케스트레이터(LLM으로 이력서 피드백·초안 생성)를 다룬다.