(WEB_PORTAL) Next.js PWA 도입기 — Turbopack과 충돌한 서비스워커 빌드

개요

사내에서 사용하는 웹 서비스를 모바일 홈 화면에 추가해 앱처럼 쓸 수 있도록 PWA(Progressive Web App)를 도입하는 작업을 진행했습니다. 기능 자체는 라이브러리 설치와 설정 몇 줄로 끝날 것으로 예상했지만, 빌드 도구 버전 차이로 인해 예상치 못한 충돌을 겪었던 경험을 공유합니다.

기술 선택 이유

• Next.js는 최신 버전부터 개발 서버 기본 번들러로 Turbopack을 채택하고 있어 로컬 개발 속도가 크게 개선됨
• PWA 관련 서비스워커 생성은 커뮤니티에서 널리 쓰이는 Next.js용 PWA 플러그인을 사용하기로 결정 — 매니페스트·서비스워커 생성 설정을 최소화할 수 있어서

문제 상황

로컬 개발 서버(next dev)에서는 문제가 없었지만, 프로덕션 빌드(next build)를 실행하면 빌드가 실패했습니다. 원인을 확인해보니, 도입한 PWA 플러그인이 아직 Webpack 플러그인 방식으로 서비스워커를 생성하는 구조였고, Next.js가 기본으로 사용하는 Turbopack 번들러와는 호환되지 않는 상태였습니다.

즉, 개발 서버는 서비스워커 자체가 개발 모드에서 비활성화되어 문제가 드러나지 않았지만, 실제 배포를 위한 프로덕션 빌드 시점에는 번들러 불일치가 그대로 실패로 이어졌습니다.

해결 방법

Next.js 프로덕션 빌드 명령에 Webpack 번들러를 명시적으로 강제하는 옵션을 추가해서, 빌드 시점에만 Webpack 기반으로 전환되도록 했습니다.

개발 서버 실행: next dev                → Turbopack 사용 (기존 그대로)
프로덕션 빌드 실행: next build --webpack  → 이 빌드에서만 Webpack으로 전환

개발 생산성은 그대로 유지하면서, 배포용 빌드에서만 PWA 플러그인과 호환되는 번들러를 쓰도록 역할을 분리한 것입니다.

회고

• 신규 번들러가 빠르게 자리 잡고 있어도, 주변 생태계(플러그인)가 아직 완전히 따라오지 못한 시기에는 "전체를 새 번들러로 통일"하기보다 "용도별로 필요한 도구를 각각 선택"하는 실용적인 절충이 더 안전하다는 걸 확인했습니다.
• 이후 유사한 빌드 도구 전환 이슈가 생기면, 개발 환경과 배포 환경의 번들링 파이프라인을 분리해서 생각하는 습관이 생겼습니다.