Nx와 Lerna로 구성하는 Node 모노레포

개요

대규모 Node 프로젝트에서 모노레포는 코드 재사용과 일관성 유지에 유리하다. Nx와 Lerna는 서로 다른 강점을 가진 도구다. 이 글은 처음 접하는 개발자도 이해할 수 있도록 Nx 모노레포 Node.js 설정과 Lerna 사용법 Node 모노레포 사례를 중심으로 설명한다.

모노레포란

정의와 목적

모노레포는 여러 패키지를 하나의 저장소에서 관리하는 방식이다. 공통 코드 공유와 버전 동기화, 일관된 빌드 파이프라인을 목적으로 한다. Node 생태계에서 흔히 사용하는 패키지 재사용 구조를 단순화한다.

주요 장점

• 패키지 간 변경을 한 번에 테스트하고 배포할 수 있다.
• 공통 설정과 개발 도구를 중앙화해 유지보수가 쉬워진다.
• 의존성 중복을 줄이고 빌드 최적화를 적용하기 쉽다.

도구 소개

Nx 개요

Nx는 모노레포를 위한 종합 툴링을 제공한다. 프로젝트 스캐폴딩, 캐시, 영향도 분석, 작업 배포 파이프라인이 핵심 기능이다. 특히 빌드 캐시와 분산 캐시로 CI 반복 시간을 줄이는 데 유리하다.

Lerna 개요

Lerna는 패키지 버전 관리와 배포에 초점을 둔 도구다. 워크스페이스와 함께 사용하면 패키지 의존성 설치와 릴리스 과정을 단순화한다. 기존 레거시 프로젝트에서 점진적으로 모노레포로 전환할 때 유용하다.

언제 어떤 도구를 선택할까

프로젝트 요구에 따라 선택이 달라진다. 빌드 최적화와 대규모 작업 스케줄링이 중요하면 Nx 중심 구성이 적절하다. 반대로 패키지 릴리스와 버전 관리가 핵심이면 Lerna를 보조로 두는 구성이 현실적이다.

설계 전략

패키지 경계 정의

작은 단위의 패키지로 분리하면 테스트와 배포가 수월하다. 도메인 기준으로 경계를 나누고 공통 유틸은 별도 패키지로 둔다. 경계를 명확히 하면 영향도 분석과 빌드 분리가 쉬워진다.

의존성 관리

중복 의존성을 줄이기 위해 루트 의존성과 패키지 별 의존성을 적절히 분배한다. 워크스페이스 기능을 활용하면 링크된 패키지를 로컬에서 참조할 수 있다. Lerna는 링크와 버전 관리를 보조한다.

빌드와 배포 파이프라인

영향도 기반 빌드를 적용하면 변경된 범위만 빌드하도록 최적화할 수 있다. Nx의 영향도 분석과 캐시를 활용하면 CI 시간이 크게 단축된다. 배포는 패키지 단위와 전체 릴리스가 혼재할 수 있으므로 정책을 명확히 정한다.

실제 설정 예시

아래 예시는 Nx 워크스페이스에 Lerna를 함께 쓰는 기본 구성이다. 먼저 워크스페이스 초기화와 워크스페이스 설정 파일을 보여준다.

1) Nx 워크스페이스 초기화

npx create-nx-workspace@latest my-workspace --preset=empty
cd my-workspace

2) package.json에 워크스페이스 추가

{
  "name": "my-workspace",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "devDependencies": {}
}

3) Lerna 초기화

npx lerna init --independent

lerna.json 예시

{
  "packages": ["packages/*", "apps/*"],
  "version": "independent",
  "npmClient": "yarn",
  "useWorkspaces": true
}

4) 간단한 패키지 구조

// packages/utils/package.json
{
  "name": "@myorg/utils",
  "version": "0.0.1",
  "main": "index.js"
}

// apps/api/package.json
{
  "name": "api",
  "version": "0.0.1",
  "dependencies": {
    "@myorg/utils": "^0.0.1"
  }
}

운영과 유지보수

테스트와 CI 설계

패키지 경계에 맞춘 테스트 스크립트를 둔다. CI는 영향도 분석 결과를 활용해 변경된 패키지만 테스트하도록 구성하면 리소스를 절약할 수 있다. Nx의 nx affected:build, nx affected:test 명령을 검토한다.

버전 정책

모든 패키지를 동시에 버전 올릴지, 독립적으로 관리할지를 결정한다. Lerna의 independent 모드는 개별 패키지 버전 관리를 지원한다. 정책은 팀 배포 방식에 맞춰 단순하게 정리하는 것이 좋다.

마무리

Nx와 Lerna는 상호 보완적이다. Nx는 빌드와 캐시에 강점을 보이고, Lerna는 패키지 배포와 버전 관리를 단순화한다. Monorepo 관리 전략 Node 관점에서 두 도구를 조합하면 개발 생산성과 운영 효율을 동시에 개선할 수 있다.