Monorepo 도구 완전 가이드: 초보자를 위한 npm workspaces, Lerna, Nx 비교

Monorepo를 처음 접하는 개발자들이 가장 어려워하는 부분 중 하나가 바로 도구 선택입니다. npm workspaces, Lerna, Nx 등 다양한 도구들이 있지만, 각각 어떤 차이가 있고 언제 사용해야 하는지 명확하지 않습니다. 이 글에서는 초보자 관점에서 각 도구의 특징과 실제 사용법을 자세히 알아보겠습니다.

워크스페이스의 개념 이해하기

Monorepo 도구를 이해하기 전에 먼저 워크스페이스(Workspace) 개념을 이해해야 합니다.

일반적인 프로젝트 구조

my-project/
├── package.json  ← 하나만 있음
├── src/
└── node_modules/

워크스페이스를 사용한 프로젝트 구조

my-project/
├── package.json          ← 메인 설정
├── packages/
│   ├── mobile/
│   │   └── package.json  ← 모바일 앱용
│   ├── server/
│   │   └── package.json  ← 서버용
│   └── shared/
│       └── package.json  ← 공통 코드용
└── node_modules/         ← 공통으로 사용

워크스페이스는 여러 개의 package.json을 하나의 프로젝트에서 효율적으로 관리하는 방법입니다. 각 패키지는 독립적인 의존성을 가지면서도, 공통 의존성은 루트에서 관리할 수 있습니다.

npm/yarn workspaces: 가장 간단한 시작점

npm workspaces는 npm에 기본으로 내장된 기능으로, 별도 설치 없이 바로 사용할 수 있습니다.

설정 방법

1단계: 루트 package.json 설정

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

2단계: 패키지 구조 생성

mkdir -p packages/mobile packages/server packages/shared
cd packages/mobile && npm init -y
cd ../server && npm init -y
cd ../shared && npm init -y

주요 명령어

# 루트에서 모든 패키지 설치
npm install

# 특정 패키지에만 라이브러리 설치
npm install express --workspace=packages/server
npm install react-native --workspace=packages/mobile

# 모든 패키지에서 명령어 실행
npm run build --workspaces

# 특정 패키지에서만 명령어 실행
npm run start --workspace=packages/mobile

장점과 한계

장점

• 설치가 필요 없음 (npm에 내장)
• 설정이 매우 간단
• 학습 곡선이 낮음
• 기본적인 의존성 관리 가능

한계

• 고급 기능 부족
• 빌드 최적화 기능 없음
• 복잡한 의존성 관리 어려움
• 배포 자동화 기능 없음

Lerna: 전통적인 Monorepo 전용 도구

Lerna는 Monorepo를 위해 특별히 개발된 도구로, npm workspaces보다 더 많은 기능을 제공합니다.

설치와 초기 설정

# Lerna 전역 설치
npm install -g lerna

# 새 프로젝트 초기화
mkdir my-app && cd my-app
lerna init

# 패키지 생성
lerna create mobile
lerna create server
lerna create shared

초기화하면 다음과 같은 구조가 생성됩니다:

my-app/
├── lerna.json        ← Lerna 설정 파일
├── package.json
└── packages/
    ├── mobile/
    ├── server/
    └── shared/

핵심 명령어들

# 모든 패키지에 의존성 설치
lerna bootstrap

# 특정 패키지에만 라이브러리 추가
lerna add express --scope=server

# 패키지 간 의존성 연결
lerna add shared --scope=server

# 모든 패키지에서 명령어 실행
lerna run build

# 변경된 패키지만 대상으로 실행
lerna run test --since

# 패키지 배포
lerna publish

Lerna의 주요 기능

똑똑한 의존성 관리

# server 패키지에서 shared 패키지를 사용한다면
lerna add shared --scope=server
# 자동으로 로컬 패키지끼리 연결됩니다

자동화된 배포

lerna publish
# 변경된 패키지들만 자동으로 버전을 올리고 배포

변경 감지

# Git을 기반으로 변경된 패키지만 빌드/테스트
lerna run build --since HEAD~1

장점과 단점

장점

• 패키지 간 의존성 관리 편의성
• 버전 관리와 배포 자동화
• 변경 감지 기능
• npm workspaces와 함께 사용 가능

단점

• 학습해야 할 개념이 많음
• 설정이 복잡할 수 있음
• 최근 업데이트가 줄어듦
• 빌드 최적화 기능 부족

Nx: 차세대 Monorepo 도구

Nx는 Google에서 개발한 현재 가장 강력하고 현대적인 Monorepo 도구입니다. 단순한 패키지 관리를 넘어서 전체 개발 경험을 혁신적으로 개선합니다.

프로젝트 생성

# 새 워크스페이스 생성
npx create-nx-workspace@latest my-app

# 대화형 설정 진행
? What to create in the new workspace? 
❯ React Native + Node
? Application name? mobile
? Which bundler would you like to use? Metro
? Test runner to use for end to end (e2e) tests? Detox
? Which CI provider would you like to use? GitHub Actions

앱과 라이브러리 추가

# React Native 앱 추가
nx generate @nrwl/react-native:app mobile

# Express 서버 추가
nx generate @nrwl/express:app server

# 공통 라이브러리 추가
nx generate @nrwl/workspace:lib shared

# 새 컴포넌트 생성
nx generate @nrwl/react-native:component my-component

# 새 API 리소스 생성
nx generate @nrwl/express:resource users

주요 명령어

# 개발 서버 실행
nx serve server          # Express 서버 실행
nx start mobile          # React Native 앱 실행

# 빌드
nx build server
nx build mobile

# 테스트
nx test server
nx test mobile

# 모든 프로젝트 대상 실행
nx run-many --target=test --all

# 변경된 부분만 빌드 (혁신적!)
nx affected --target=build

Nx의 혁신적인 기능들

의존성 그래프 시각화

nx graph

이 명령어 하나로 브라우저에서 프로젝트 간 의존성을 그래프로 시각화할 수 있습니다.

지능적인 빌드 (Affected)

# mobile 앱 코드만 변경했다면
nx affected --target=build
# → server는 빌드하지 않아 시간을 절약합니다

강력한 캐싱

# 첫 번째 빌드
nx build server

# 코드 변경 없이 다시 빌드하면
nx build server
# → 캐시된 결과를 즉시 반환

코드 생성기 Nx는 다양한 템플릿을 통해 보일러플레이트 코드를 자동 생성합니다.

프로젝트 구조 예시

my-app/
├── apps/
│   ├── mobile/           # React Native 앱
│   │   ├── src/
│   │   ├── app.json
│   │   └── project.json  ← Nx 프로젝트 설정
│   └── server/           # Express 서버
│       ├── src/
│       └── project.json
├── libs/
│   ├── shared/           # 공통 라이브러리
│   │   ├── src/
│   │   └── project.json
│   └── ui/               # 공통 UI 컴포넌트
├── nx.json              ← Nx 메인 설정
└── workspace.json       ← 워크스페이스 설정

장점과 단점

장점

• 혁신적으로 빠른 개발 경험
• 지능적인 빌드와 캐싱
• 풍부한 플러그인 생태계
• 대규모 프로젝트에 최적화
• 자동 코드 생성
• 의존성 그래프 시각화

단점

• 높은 학습 곡선
• 작은 프로젝트에는 과도할 수 있음
• 많은 설정 파일
• 초기 설정 복잡성

Rush: 대기업을 위한 도구

Rush는 Microsoft에서 개발한 도구로, 매우 큰 규모의 프로젝트를 위해 설계되었습니다.

특징

• 수십 개의 패키지가 있는 대규모 프로젝트 대상
• 엄격한 의존성 관리
• 대규모 팀을 위한 고급 기능
• 초보자에게는 복잡함

일반적인 웹 애플리케이션 개발에서는 거의 사용되지 않으므로, 이 글에서는 자세히 다루지 않겠습니다.

도구 선택 가이드

1단계: npm workspaces로 시작

추천 상황

• Monorepo를 처음 시도하는 경우
• 간단한 프로젝트 구조
• 별도 도구 학습 시간이 부족한 경우

시작하기

mkdir my-app && cd my-app
npm init -y
# package.json에 "workspaces": ["packages/*"] 추가
mkdir -p packages/mobile packages/server packages/shared

2단계: 복잡해지면 Lerna 고려

추천 상황

• 패키지 간 의존성이 복잡해질 때
• 배포와 버전 관리 자동화가 필요할 때
• npm에 패키지를 배포해야 할 때

마이그레이션

npm install -g lerna
lerna init
# 기존 packages 폴더 그대로 사용 가능

3단계: 대규모 프로젝트라면 Nx

추천 상황

• 빌드 시간이 오래 걸릴 때
• 팀 규모가 클 때
• 고급 개발 도구가 필요할 때
• 최신 개발 경험을 원할 때

마이그레이션

npx create-nx-workspace@latest
# 기존 코드를 새 구조로 이동

실제 체험해보기

npm workspaces를 5분만에 체험해볼 수 있는 방법입니다:

# 프로젝트 생성
mkdir test-monorepo && cd test-monorepo

# 루트 package.json 생성
echo '{"name":"test","private":true,"workspaces":["packages/*"]}' > package.json

# 패키지 폴더 생성
mkdir -p packages/app packages/utils

# 각 패키지 초기화
cd packages/app && echo '{"name":"app","main":"index.js"}' > package.json
cd ../utils && echo '{"name":"utils","main":"index.js"}' > package.json

# 의존성 설치
cd ../../ && npm install

echo "완성! packages 폴더를 확인해보세요"

이렇게 간단한 실습을 통해 Monorepo의 기본 구조를 이해할 수 있습니다.

현실적인 추천

스타트업이나 개인 프로젝트

npm workspaces를 추천합니다. 별도 학습 비용 없이 바로 시작할 수 있고, 나중에 필요에 따라 다른 도구로 쉽게 마이그레이션할 수 있습니다.

중간 규모 팀 프로젝트

Lerna를 고려해보세요. 배포 자동화와 패키지 관리의 편의성이 개발 효율성을 크게 향상시킵니다.

대규모 팀이나 복잡한 프로젝트

Nx를 강력히 추천합니다. 초기 학습 비용은 있지만, 장기적으로 개발 경험과 생산성이 혁신적으로 개선됩니다.

마이그레이션 경로

다행히 이 도구들은 서로 마이그레이션이 가능합니다:

npm workspaces → Lerna → Nx

따라서 npm workspaces로 시작해서 프로젝트가 복잡해지면 단계적으로 더 강력한 도구로 이동하는 것이 현실적인 접근법입니다.

결론

Monorepo 도구 선택은 프로젝트의 규모와 팀의 상황에 따라 달라집니다. 초보자라면 npm workspaces로 시작해서 Monorepo의 개념을 익히고, 필요에 따라 더 강력한 도구로 발전시켜 나가는 것을 추천합니다.

가장 중요한 것은 도구에 매몰되지 않고, 실제 개발 생산성과 팀의 협업 효율성을 높이는 방향으로 선택하는 것입니다. 각 도구의 특성을 이해하고 상황에 맞는 선택을 하시길 바랍니다.