Beyond the Docs: The Hidden Challenges of Nx to Turborepo Migration

Context

Nx 기반 모노레포에서 custom executor, 숨겨진 빌드 로직, 복잡한 캐싱이 블랙박스처럼 작동하면서 팀의 자율성이 저하되었다. 공유 라이브러리 변경 시 불필요한 전체 빌드 트리거, 단일 저장소의 복잡성으로 인한 독립 배포 어려움이 주요 문제였다.

Technical Solution

• 프로젝트 구조 재설계: Nx의 workspace.json 및 project.json 기반 구조를 버리고, 각 앱별 독립 package.json과 루트 package.json의 workspaces 필드로 변경
• 빌드 설정 파이프라인 단순화: nx.json을 turbo.json으로 교체하고 명시적 task 파이프라인 정의 (build, test, lint, dev 등에 dependsOn, outputs, cache 속성 설정)
• Next.js 설정 직접 관리: withNx 플러그인 제거 후 next.config.js에서 SVGR, 경로 별칭, 배포 디렉토리를 수동으로 설정
• SVG 처리 설정 복원: SVGR 기본값이 viewBox를 제거하는 문제 해결을 위해 svgoConfig에 removeViewBox: false, cleanupIds: false 옵션 명시
• 환경 변수 처리 자동화: Turborepo가 앱 디렉토리에서 태스크를 실행하더라도 Next.js 13+ 이상의 @next/env 디렉토리 순회 메커니즘으로 루트 .env 파일 자동 감지 (추가 설정 불필요)

Key Takeaway

모노레포 도구 선택 시 추상화 계층의 투명성과 팀의 표준 도구 직접 제어 가능성이 장기적 유지보수성을 좌우한다. Turborepo는 task runner로서 한 가지 역할에 집중하므로, 마이그레이션 시 기존 도구의 숨겨진 설정 (SVGR, 경로 별칭 등)을 명시적으로 드러내고 재구성해야 한다.