Next.js 14 & App Router 환경에서 Progressive Web App(PWA) 수동 구현 가이드

핵심 기술: 본 콘텐츠는 웹사이트를 네이티브 앱처럼 홈 화면에 추가할 수 있게 하는 Progressive Web App(PWA) 기능을 Next.js 14의 App Router 환경에서 수동으로 구현하는 방법을 상세하게 다룹니다. 특히 next-pwa 라이브러리의 App Router 미지원 문제를 해결하고, 웹 앱 매니페스트(manifest.json) 및 서비스 워커(sw.js)를 직접 설정하는 과정을 중심으로 설명합니다.

기술적 세부사항:
* PWA 기본 조건: HTTPS, 웹 앱 매니페스트 파일, 서비스 워커 등록.
* next-pwa 라이브러리 문제: Next.js 14 App Router 방식과의 호환성 문제로 인한 빌드 에러 발생.
* 수동 구현 접근법: next-pwa 대신 직접 PWA 관련 파일들을 설정하는 방식 채택.
* 웹 앱 매니페스트 (manifest.json): 홈 화면 아이콘(192x192)과 스플래시 화면 아이콘(512x512)을 포함한 필수 정보 구성.
* 서비스 워커 (sw-template.js, sw.js):
* 빌드 시점에 동적으로 캐시명(예: __BUILD_SW_DATE__)을 주입하기 위한 sw-template.js 파일 생성.
* fs, path 모듈을 사용한 빌드 스크립트(replace-sw-date.ts)를 통해 __BUILD_SW_DATE__ 변수를 실제 빌드 날짜로 치환하여 public/sw.js 파일 생성.
* sw.js 파일 내 캐싱 전략(설치, 활성화, 가져오기 이벤트) 구현.
* 서비스 워커 등록: 클라이언트 컴포넌트에서 navigator.serviceWorker.register('/sw.js')를 사용하여 서비스 워커 등록.
* 'Add to Home Screen' 이벤트 처리: beforeinstallprompt 이벤트를 사용하여 사용자에게 PWA 설치 프롬프트 제공 및 useAddToHomeScreen 커스텀 훅 구현.
* 모노레포 CI/CD: Nx 모노레포 환경에서 특정 앱에만 PWA 기능을 적용하기 위해 CI/CD 파이프라인에서 스크립트 실행 제어 (ci.yml 예시).
* 플랫폼별 동작: 안드로이드에서는 자동, iOS는 사파리 공유 기능을 통한 추가 필요.

개발 임팩트:
* 웹사이트에 앱과 유사한 사용자 경험 제공 및 접근성 향상.
* 오프라인 캐싱, 푸시 알림 등의 PWA 기능 기반 마련.
* next-pwa 라이브러리 제약 없이 최신 Next.js 버전 및 App Router 환경에서 PWA 구현 가능.
* AI(ChatGPT)를 활용하여 개발 시간 단축 및 문제 해결 경험 공유.

커뮤니티 반응: (본문에서 직접적인 커뮤니티 반응 언급 없음)

톤앤매너: 개발 과정에서 발생한 문제점과 해결 과정을 솔직하고 명확하게 공유하며, 실무 적용 사례와 구체적인 코드 예시를 제공하는 전문적인 톤을 유지합니다.