Firebase에서 Cloudflare Workers로, Next.js 모노레포 마이그레이션 전략

Context

Firebase Hosting의 Next.js 최신 기능 지원 부족으로 인한 개발 제약 발생. 복잡한 GitHub Actions 파이프라인의 잦은 실패와 높은 관리 비용 초래. 트래픽 증가에 따른 SSR 비용 예측 불가능 및 운영 부담 가중.

Technical Solution

• @opennextjs/cloudflare 어댑터를 도입하여 Next.js 빌드 결과물을 Cloudflare Workers 런타임에 최적화된 형태로 변환
• Nx와 pnpm workspaces 기반 모노레포 구조를 유지하며 Makefile을 통해 앱별 빌드 및 배포 프로세스 표준화
• wrangler.jsonc 설정을 통해 nodejs_compat 플래그를 활성화하고 런타임 환경의 Node.js API 호환성 확보
• Cloudflare Zero Trust Access를 네트워크 레벨에 배치하여 코드 수정 없이 스테이징 환경의 인증 및 접근 제어 구현
• compatibility_date를 2025-04-01 이후로 설정하여 process.env를 통한 환경 변수 주입 및 Zod 스키마 검증 체계 유지
• Next.js 16.2의 공식 Adapter API 도입을 통해 프레임워크와 플랫폼 간의 표준화된 인터페이스 기반의 안정적 확장 설계

Key Takeaway

플랫폼 종속적인 워크라운드보다 표준화된 Adapter API와 같은 공통 계약을 통한 인프라 추상화가 장기적인 유지보수성과 최신 기능 도입 속도를 결정함.