모노레포 기반의 Next.js 프로젝트에서 프런트엔드 개발의 최대 병목은 백엔드 API의 완성 유무다. 단순히 로컬 환경에 국한된 모킹을 넘어, Vercel 배포 환경에서도 운영 환경과 동일한 비즈니스 로직을 검증하기 위해 가짜 도메인(Dummy Domain) 과 서버 사이드 모킹(Server-side Mocking) 을 결합한 아키텍처를 구축하였다.

그림 1. 환경 변수(NEXT_PUBLIC_API_MODE)에 따른 모킹/리얼 API 분기 아키텍처

1. 배포 환경 이원화 및 병렬 워크플로우

인프라 비용 효율화와 개발 리드타임 단축을 위해 배포 환경을 API 모드에 따라 분리하였다. 백엔드 의존성을 제거함으로써 프런트엔드 단독 프리뷰 환경을 가동한다.

1.1 환경별 데이터 흐름 및 개발 공정

1.2 병렬 개발을 통한 생산성 증빙

기존의 직렬적 구조(API 개발 완료 후 프런트엔드 착수)를 탈피하고, API 명세 확정 즉시 모킹을 통해 개발을 시작하는 Contract-Driven Development를 지향한다.

• 대기 시간 제거: 백엔드 배포를 기다리는 유휴 시간(Idle Time)을 실질 개발 시간으로 전환한다.
• 인프라 독립성: DB 및 서버 환경 구축에 소요되는 오버헤드를 배제하고 기능 구현에 집중한다.

2. 서버 사이드 모킹 활성화: instrumentation.ts 활용

Next.js App Router 환경에서는 코드 실행 주체가 클라이언트(Browser)와 서버(Node.js)로 이원화된다. 브라우저의 Service Worker는 서버 런타임에서 발생하는 요청을 가로챌 수 없으므로, Server Action이나 SSR(Server Side Rendering) 단계의 통신을 모킹하기 위해서는 별도의 서버 사이드 인프라가 필요하다.

2.1 서버 런타임 초기화: register() 후크

Next.js가 제공하는 instrumentation.ts는 서버 인스턴스가 생성되는 시점에 실행되는 진입점이다. 이를 통해 서버리스 환경이나 로컬 서버 가동 시 MSW의 setupServer를 선제적으로 구동하여 서버 환경에서의 모든 fetch 요청을 제어한다.