안녕하세요, 소플입니다.

개발하는 프로젝트의 규모가 커지면 여러 개의 프로젝트 또는 패키지들이 생기게 됩니다.

그리고 서로 의존하고 있는 이러한 패키지들을 하나의 repository에서 관리할 필요성이 생기게 됩니다.

이처럼 하나의 repository에서 여러 패키지 또는 프로젝트를 관리하는 방식을 모노레포(Monorepo) 라고 합니다.

모노레포 환경을 구성하기 위한 도구로는 npm workspaces, Yarn Workspaces, Lerna, Nx, Turborepo 등이 있는데,

이번 매거진에서는 npm에서 공식 기능으로 제공하는 npm workspaces에 대해 살펴보도록 하겠습니다.

---

npm workspaces란?

npm workspaces는 npm 버전 7에서 처음 등장한 기능으로,

여러 패키지를 단일 repository 내에서 관리할 수 있게 해주는 기능입니다.

앞에서 말한 모노레포 환경을 구성하고 쉽게 관리할 수 있게 해주는 것이죠.

아래와 같이 package.json 파일에서 workspaces 속성을 통해 workspace들을 관리할 수 있습니다.

{
    "name": "workspace-example",
    "version": "1.0.0",
    "workspaces": [
        "packages/a",
        "packages/b",
        "packages/c"
    ]
}

여기서 하나의 workspace는 하나의 패키지를 의미한다고 보면 됩니다.

그리고 위와 같은 형태의 package.json 파일을 이용하여 npm install명령을 실행하게 되면,

node_modules 폴더에 자동으로 각 패키지들의 Symbolic link가 걸리게 됩니다.

기존에는 로컬 패키지 연동을 위해 npm link 명령어를 사용해서 Symbolic link를 수동으로 걸어줘야 했는데,

workspaces 기능을 사용하면 그런 작업들을 알아서 해주는 것이죠.

npm workspaces 특징

지금부터는 npm workspaces의 특징을 하나씩 살펴보도록 하겠습니다.

다중 패키지 관리

npm workspaces를 사용하면 하나의 리포지토리에서 여러 패키지를 동시에 관리할 수 있습니다.

각 패키지는 독립적인 폴더와 package.json 을 가지며,

repository 루트에서 모든 패키지의 의존성을 한 번에 설치하거나 업데이트할 수 있습니다.

단일 node_modules 폴더

워크스페이스 내의 모든 패키지에 대한 의존성은 루트 폴더의 node_modules 폴더에 설치됩니다.

중복되는 의존성은 하나로 합쳐져 관리되므로 디스크 공간을 절약할 수 있고 설치 속도도 빨라집니다.

패키지 간의 의존성 link

npm workspaces는 동일한 모노레포 내의 패키지 간에 의존성을 자동으로 link합니다.

예를 들어, 한 패키지가 다른 패키지를 의존성으로 사용할 경우,

해당 의존성은 별도의 네트워크 요청 없이 바로 로컬에서 링크되어 개발 및 테스트 환경이 빨라집니다.

의존성 관리의 일관성

모든 패키지가 하나의 루트 package-lock.json 파일을 공유하므로 의존성 트리의 일관성을 유지할 수 있습니다.

이를 통해 CI/CD 환경에서도 동일한 의존성을 보장할 수 있다는 특징이 있습니다.

npm workspaces 사용해보기

지금부터는 npm workspaces를 사용하는 예시를 순서대로 살펴보도록 하겠습니다.

1. 새 프로젝트 생성

먼저 워크스페이스를 관리할 최상위 프로젝트를 생성합니다.

mkdir my-monorepo
cd my-monorepo
npm init -y

2. package.json 파일 수정

다음으로 프로젝트 최상위 폴더에 위치한 package.json 파일에 아래와 같이 workspaces 필드를 추가합니다.

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

3. 하위 패키지 생성

다음으로는 워크스페이스로 관리할 패키지를 생성합니다.

이 때 각 패키지에는 자체적인 package.json 파일이 필요합니다.

mkdir -p packages/package-a
cd packages/package-a
npm init -y

mkdir -p ../package-b
cd ../package-b
npm init -y

4. 패키지 의존성 설치

이제 최상위 폴더에서 npm install 명령어를 실행합니다.

그러면 모든 워크스페이스 패키지들의 의존성이 한 번에 루트 폴더의 node_modules 폴더에 설치됩니다.

npm install

5. 패키지 간 의존성 설정

이후 워크스페이스 내부 패키지 간의 의존성을 설정합니다.

예를 들어, package-a가 package-b를 의존성으로 사용하는 경우,

package-a의 package.json을 아래와 같이 수정하면 됩니다.

{
    ...
    
    "dependencies": {
        "package-b": "1.0.0"
    }

    ...
}

아래 화면은 위 일련의 과정을 통해 생성된 폴더 구조와 package.json 파일을 캡처한 것입니다.

node_modules 폴더가 루트 폴더에만 위치하는 것을 볼 수 있으며,

각각의 패키지에 대한 Symbolic link가 생성되어 있는 것도 볼 수 있습니다.

그리고 각 패키지 폴더 내에 package.json 파일이 각각 존재하는 것도 볼 수 있습니다.

NOTE: 워크스페이스 명령어 실행

npm 명령어는 워크스페이스 전체 또는 특정 패키지에서 실행할 수 있습니다.

예를 들어, npm install --workspaces 명령을 실행하면 각각의 패키지 의존성이 한 번에 설치됩니다.

그리고 -ws 또는 --workspace 옵션을 사용하면 특정 패키지에만 명령을 실행할 수 있습니다.

# 모든 워크스페이스에 대한 의존성 설치
npm install --workspaces

# package-a에서 build 스크립트 실행
npm run build --workspace=package-a

# package-a에 react 설치 (의존성 추가)
npm install react --workspace=package-a

---

🔗 참고 링크

• npm RFC 26
• https://docs.npmjs.com/cli/v10/using-npm/workspaces

---

이번 매거진에서는 npm에서 모노레포를 위해 공식 기능으로 제공하는 npm workspaces에 대해서 살펴보았습니다.

사실 모노레포를 위한 더 좋은 도구들이 많지만, 순정(?)을 좋아하는 분들에게는 간단하게 모노레포를 설정해서 사용하기에는 좋지 않을까 싶습니다.

그럼 저는 다음에 또 유익한 글로 찾아뵙겠습니다!

지금까지 소플이었습니다. 감사합니다 😀