📦 Monorepo Tutorial

Monorepo에 대해 학습한 내용을 정리한 글이다.

📦 Monorepo?

여러 프로젝트를 진행하다 보면 동일한 모듈을 다른 프로젝트에도 같이 사용해야 될 경우가 생긴다. 예를 들어 backend에서 admin 과 실제 서비스 프로젝트 간의 모델, 도메인 비지니스 로직에 대한 코드나 혹은 react와 react-native 사이의 컴포넌트 공유 등 여러가지 케이스가 있을 수 있다. 이렇게 모듈을 공유해야되는 상황에서 중복되는 모듈마다 리포지토리 분리해서 패키지 매니저에 등록하고 사용하게 되면 개발, 테스트, 배포 에 있어서 관리하기가 어려워진다. 모노리포는 하나의 리포지토리에 여러 패키지들을 두는 구조이다.

Monorepo 장점

• test, build, release 프로세스를 한 번에 진행할 수 있다.
• 하나의 저장소에서 issue를 처리할 수 있다.
• 모듈별로 개별적인 버전관리
• 패키지 매니저에 등록하지 않고도 코드를 공유하기 쉬워진다.

Monorepo 단점

• 러닝커브 와 초기셋팅
• 커진 리포지토리 사이즈?

이것 말고도 모노리포로 구성해서 좀 더 번거로워 지는 부분들도 있겠지만 좀 더 사용해봐야 할 것 같다.

Monorepo를 구성하는 방법

모노리포는 리포지토리를 구성한는 형식이기 때문에 여러가지 도구를 통해서 구성할 수 있다. 별다른 도구 없이도 하나의 리포안에 폴더를 구분하고 node_module간의 심볼릭 링크를 통해서 구현할 수 있겠지만 매번 링크를 거는 방법은 비효율적이고 번거롭다. 여기선 가장 많이 사용하는 방법인 Yarn workspace 와 Lerna 에 대해 간단히 소개해보려고 한다.

Yarn workspace

yarn workspace는 패키지 아키텍쳐를 설정하는 새로운 방법이고 기본적으로 1.0버전부터 사용할 수 있다고 한다. yarn workspace를 이용하면 좀 더 쉽게 모노리포 안에 여러 패키지들의 의존성을 관리할 수 있다. root 폴더와 패키지들로 구성할 수 있는데 모든 패키지들에 대한 의존성을 한번의 yarn install 로 처리할 수 있다. 또한 모듈은 hoist 되어서 root 폴더의 node_modules 폴더에 설치된다. 물론 공통된 모듈인데 버전만 다를 경우엔 해당 패키지 node_modules에 설치된다.

아래 튜토리얼을 따라해보면 어떤식으로 동작하는지 좀 더 쉽게 이해할 수 있다.

Repo Structure

구성해보려고 하는 모노리포의 구조는 다음과 같다. 보통 packages라는 폴더 아래 패키지들을 모아서 관리하지만 다른이름으로 바꿔도 무관하다.

1
2
3
4
5

├── package.json
└── packages
    ├── server
    ├── shared
    └── web

root package.json 작성

root directory는 패키지로 배포될리 없기 때문에 private으로 설정하고 workspaces에는 패키지 폴더명을 배열로 넘길 수 있다. 패턴도 사용이 가능하다.

yarn init 후 아래 property를 추가해주면 된다.

1
2
3
4
5
6

{
  "private": true,
  "workspaces": [
    "packages/*"
  ]	
}

패키지별 package.json 생성

1
2
3

cd packages/shared && yarn init -y
cd packages/server && yarn init -y
cd packages/web && yarn init -y

패키지명 변경

package.json 이 생겼지만 npm 에서 따로 설치한 모듈과 구분해주기 위해서 앞에 prefix를 붙여주는 것이 좋다. 여기선 예시로 @project로 설정하였다.

1
2
3
4
5
6

{
  "name": "@project/server",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

yarn install

root 폴더로 이동후 yarn install 을 하면 node_modules에 패키지들이 심볼릭 링크가 자동으로 걸려있다. 이걸통해서 패키지간에 모듈 상호참조가 가능해진다.

1
2
3
4

└── @project
    ├── server -> ../../packages/server
    ├── shared -> ../../packages/shared
    └── web -> ../../packages/web

간단한 코드 작성

shared 패키지에 어떤함수를 추가하고 server패키지에서 shared모듈을 참조해서 사용하는 예시이다.

packages/shared/index.js

1
2
3

module.exports = () => {
  console.log('Hello Shared!');
};

shared 모듈을 로딩하기전에 server패키지에 shared를 의존성으로 추가해주어야 한다.

(수동으로 추가해도 무방하다.)

1

yarn workspace @project/server add @project/shared@1.0.0

packages/server/index.js

1
2

const sharedFunc = require('@project/shared');
sharedFunc();

server/index.js 실행

1

node packages/server/index

npm 모듈 추가 (hoist)

packages/server/package.json

1
2
3
4
5
6

"dependencies": {
  "@project/shared": "1.0.0",
  "axios": "^0.19.0",
  "jest": "^24.8.0",
  "query-string": "^6.7.0"
}

packages/web/package.json ,
packages/shared/package.json

1
2
3
4
5

"dependencies": {
  "query-string": "^6.7.0",
  "jest": "24.0.0",
  "axios": "0.18.0"
}

모듈을 다음과 같이 추가한 후 root에서 yarn install 을 하면 패키지별로 공통된 모듈에 같은 버전이라면 hoist되어서 root 폴더에 node_modules에 설치된다. 버전이 다르다면 패키지아래 node_modules가 사용될 것이다. 만약 hosit를 기능으로 인해 경로상의 문제나 다른 문제가 발생한다면 nohoist 옵션을 사용할 수 있다. 이에 대한 자세한 설명은 아래 참조 링크를 남겨두었다.

Lerna

Lerna는 모노리포의 workflow를 최적화 시켜주는 툴이다. 여기서 말하는 workflow란 test, build, versioning, publishing 등과 같은 활동들을 뜻한다. 물론 모노리포안에 여러 패키지간의 의존성을 관리해주는 일도 하고 있다. 그러나 최근에는 의존성관리 와 같은 기능은 yarn workspace에 위임하여 같이 사용하는 추세인 것 같다.

이 글에선 yarn workspace와 같이 사용하는 튜토리얼을 만들어보었다.

위에서 구성해놓은 yarn workspace에 lerna를 추가한다.

lerna는 root에 설치해야하므로 -W 옵션을 붙여서 추가할 수 있다.

1

yarn add -W -D lerna

lerna 설정파일을 만들어준다.

1

npx lerna init

yarn workspace와 같이 사용하기 위해 lerna.json파일을 수정한다.

1
2
3
4
5

{
  "useWorkspaces": true,
  "npmClient": "yarn",
  "version": "0.0.0"
}

모든 패키지에 test scripts를 추가한다.

해당 스크립트는 단순히 콘솔에 패키지명을 출력해준다.

1
2
3

"scripts": {
  "test": "echo test $npm_package_name"
}

lerna run command를 통해서 패키지의 script를 실행시킨다.

1

npx lerna run test

출력결과

1
2
3

test @project/web
test @project/shared
test @project/server

—scope 옵션을 통해서 특정 패키지만 실행하는 것도 가능하다.

1

npx lerna run test --scope={@project/web,@project/server}

lerna 에는 run말고도 유용한 command가 많이 존재한다.

아래에는 간단히 주요명령어에 대해 정리해보았다.

• lerna bootstrap - 패키지들의 의존성을 설치한다. yarn workspace를 사용중이라면 yarn에 위임한다.
• lerna clean - 패키지에 node_modules 폴더를 모두 삭제한다.
• lerna run - 패키지의 특정 scripts를 실행할 수 있다.
• lerna exec - 패키지 경로에서 특정 command를 실행할 수 있다.
• lerna version - 패키지별로 변경된 패키지만 version bump

자세한 옵션이나 사용예시는 lerna github page을 참고하도록 하자.

마무리

프로젝트를 하다보면 “이 모듈은 다른곳에서도 쓰일 것 같은데?” 이렇게 생각해본게 많이 있었던 것 같다.
진행했던 react프로젝트 중 여러 프로젝트에서 공통적으로 사용하는 UI들은 storybook과 함께 component 모음을 만들어두고 사용한 적이 있다. 하지만 프로젝트 리포지토리가 분리되어 있었고 같이 사용하기 위해선 npm git repository를 이용하거나 git submodule을 선택해야했는데 개발을 위해서 프로젝트를 여러개 띄워야하고 조그만 변경에도 버전을 올리고 다시 받아야되서 번거로웠던 경험이 있다. 만약 모노리포로 구성되어있다면 좀 더 나은 방법으로 관리할 수 있지 않았을까 하는 생각이 든다.
모노리포가 멀티리포보다 무조건 좋다고 생각하진 않는다. 다만 프로젝트를 구성하는 방법도 여러가지 알아두면 상황에 맞춰서 좋은 구조를 선택할 수 있을것 같다.

Ref

• https://yarnpkg.com/blog/2017/08/02/introducing-workspaces/
• https://yarnpkg.com/en/docs/workspaces
• https://yarnpkg.com/blog/2018/02/15/nohoist/
• https://github.com/lerna/lerna