Turbopack 전환 시 서버 패키지 번들 오류 해결

Next.js 프로젝트에서 Turbopack으로의 번들러 전환 과정 중에, 서버 환경에서만 사용되는 특정 라이브러리들이 제대로 번들되지 않는 문제를 만났다. openapi-to-postmanv2 패키지를 serverExternalPackages 설정에 추가한 작업인데, 이건 단순한 설정 수정을 넘어서 번들러 마이그레이션에서 자주 마주치는 호환성 문제를 어떻게 풀어나가야 하는지를 보여주는 사례다.

serverExternalPackages가 필요한 이유

Next.js의 next.config.ts에서 serverExternalPackages 설정은, 서버 사이드에서만 실행되는 의존성들을 외부 패키지로 표시해서 번들에 포함시키지 않도록 한다. 예를 들어 API 생성 도구처럼 빌드 시점이나 런타임의 서버 로직에만 필요한 라이브러리가 있다면, 이를 브라우저로 보낼 필요는 없다.

기존 번들러(Webpack)에서는 이런 패키지들이 자동으로 또는 묵시적으로 외부 처리되곤 했다. 그런데 번들러를 Turbopack으로 업그레이드하면서 설정이 더 엄격해지거나 일부 암묵적 동작이 명시적 설정으로 변하는 경우가 생긴다. 이게 그 사례였다.

문제 인식과 해결 과정

번들러를 바꿀 때 자주 발생하는 패턴이다. 점진적 마이그레이션 과정에서 기존 동작이 보장되지 않는다는 걸 배운다. Webpack→Turbopack, Next.js 버전 업→다음 버전 등의 전환 시점에 이런 "예전엔 되던 게 지금은 안 된다" 케이스가 튀어나온다.

next.config.ts 설정 패턴

// before: 명시적 설정 없음
const nextConfig = {
  // ...
}

// after: serverExternalPackages에 추가
const nextConfig = {
  serverExternalPackages: ['openapi-to-postmanv2'],
  // ...
}

이 한 줄의 추가가 빌드 안정성을 크게 올린다. 서버 환경에서 필요한 모듈들을 명시함으로써, 번들러가 어떤 패키지가 외부 의존성인지 확실히 알 수 있게 된다.

팀 관점의 회고

이런 작업을 진행하면서 깨닫게 되는 몇 가지:

• 문서화의 중요성: Turbopack 마이그레이션 가이드나 설정 변경 사항을 정확히 숙지하고 있어야, 이런 호환성 문제를 빠르게 찾고 대응할 수 있다. 팀이 새로운 도구를 도입할 때 체크리스트를 미리 만드는 게 이런 이유다.

• 테스트 자동화: 빌드 과정이 CI/CD 파이프라인에서 충분히 테스트되어야 이런 문제를 바로 캐치할 수 있다. 로컬 빌드만 통과하고 배포 환경에서 깨지는 일을 줄일 수 있다.

• 점진적 리팩토링의 리스크: 번들러 같은 기반 인프라를 바꿀 때는 아주 작은 변경 하나가 예상 밖의 영향을 줄 수 있다. 따라서 변경을 최대한 작고 검증 가능하게 유지하는 게 중요하다.

이 수정은 몇 줄짜 보이지만, 뒤에는 "왜 번들러가 이 패키지를 포함시키려고 했나", "빌드 환경과 런타임 환경의 차이는 뭔가" 같은 질문들이 있다. 그리고 그걸 명확히 이해하고 있을 때 비슷한 상황에서 빠르게 대응할 수 있다.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.