Next.js를 사용하면서...

SOSO·2024년 11월 12일

Next.js를 사용하면서...

Next.js를 사용하면서 겪었던 트러블 슈팅 경험을 정리해보았다

getServerSession 오류

서버 세션을 가져올 때 예상과 다르게 세션이 정상적으로 가져와지지 않았었는데, NextAuth 설정이나 서버와 클라이언트 간 통신 문제를 다시 확인하면서 원인을 파악할 수 있었다. 이 내용을 블로그에 정리해서 나중에 참고할 수 있도록 했다.

서버 사이드 렌더링(SSR)과 클라이언트 사이드 렌더링(CSR) 혼합 시 문제

SSR과 CSR을 섞어 쓸 때 데이터를 서버에서 받아올지 클라이언트에서 받아올지 결정하는 게 중요했었적이 있었다.
특히 getServerSideProps를 사용할지 아니면 클라이언트에서 데이터를 받아올지 선택하는 과정에서 Next.js의 페이지 로딩 속도나 사용자 경험이 영향을 받아서 페이지별로 어떤 방식이 더 적절할지 고민하면서 구조를 개선했다.

Next.js와 TypeScript 설정 오류

Next.js 프로젝트에 TypeScript를 처음 도입했을 때, 타입 설정에서 예상치 못한 오류가 많이 발생했다. 특히 외부 라이브러리 타입 정의가 제대로 되어 있지 않아서 @types 패키지를 따로 설치하거나 tsconfig.json 파일을 세밀하게 조정해야 했는데, 에러를 하나하나 해결해 나가면서 TypeScript에 익숙해질 수 있었던것 같다.

환경변수(.env) 설정 문제

프로젝트를 배포할 때 .env 파일에 중요한 API 키나 환경 변수를 설정하는데, 클라이언트에서 접근하지 않아야 할 변수가 노출되는 경우가 있었다. Next.js에서는 NEXTPUBLIC 접두사가 붙어야 클라이언트에 전달되는데, 이를 실수로 서버에서만 필요한 변수에도 붙여버려서 클라이언트에서도 접근이 가능하게 되는 문제를 발견했어. 이후에는 환경 변수를 구분해서 관리하고 배포 환경에서도 다시 한번 점검하는 습관을 들였다.

OAuth 소셜 로그인 리다이렉트 문제

TripMate with Next.js에서 OAuth로 소셜 로그인 기능을 구현할 때, 특정 브라우저에서 리다이렉트 URL이 제대로 작동하지 않는 문제가 발생했었다.
리다이렉트 URL을 설정할 때 경로나 스코프(scope) 설정이 맞지 않아서 종종 로그인이 실패했었는데, OAuth 제공업체의 설정을 꼼꼼히 확인하고 NextAuth 설정도 재검토하면서 문제를 해결했다.

이미지 최적화 문제

Next.js의 next/image를 사용해서 이미지를 최적화하는 기능을 활용하려고 했는데, 다양한 크기나 포맷에 맞게 이미지를 자동으로 조정하는 데 문제가 있었다. 특히, 동적으로 로딩되는 이미지에서 로딩 속도가 늦어지거나 이미지가 깨져서 보이는 문제가 발생했었는데 이를 해결하기 위해 loader와 sizes를 세밀하게 설정하고, 이미지의 포맷과 크기를 서버 사이드에서 미리 조정하여 로딩 속도를 개선할 수 있었다.

라우트 변경 시 상태 유지 문제

페이지 간 이동 시에 상태를 어떻게 유지할지가 문제가 되기도 했었다. Next.js의 페이지 네비게이션은 기본적으로 페이지를 새로 로드하기 때문에, 상태가 초기화되는 문제가 있었는데 상태를 유지하려면 useState나 useReducer를 페이지 컴포넌트 외부에서 관리하거나, Redux를 이용해 상태를 글로벌하게 관리해야 했다.

배포 후 undefined 에러 문제

배포 후 특정 페이지에서 undefined 에러가 발생했던 적이 있었다. 주로 컴포넌트가 의도치 않게 렌더링될 때 생겼는데, useState나 useEffect에서 초기값을 설정하지 않거나, 조건부 렌더링이 제대로 적용되지 않아서 문제가 생겼던것 같다. 이를 해결하려면 상태 값 초기화나 API 요청의 결과를 조건부로 처리하는 로직을 추가해야 했다.