Nest.js에서 MonoRepo 설정

Source: Dev.to

Monorepos는 두 개 이상의 서비스나 공유 라이브러리를 관리하는 백엔드 팀에게 기본 선택이 되고 있습니다. Nest.js는 모노레포 환경에서 매우 잘 작동하며, 이를 위한 내장 지원까지 제공합니다.

이 글에서 배우게 될 내용:

• 모노레포가 무엇이며 왜 유용한지
• Nest.js가 모노레포를 어떻게 지원하는지
• Nest.js 모노레포를 단계별로 설정하는 방법
• 확장 가능한 깔끔한 폴더 구조
• 흔히 마주치는 팁과 함정

불필요한 내용은 없습니다. 바로 작동하게 만드는 데 필요한 것만 제공합니다.

Monorepo란 무엇인가?

monorepo는 여러 애플리케이션과 공유 라이브러리를 포함하는 단일 저장소입니다.

별도의 저장소를 사용하는 대신:

api-repo/
auth-repo/
shared-utils-repo/

하나의 저장소에 통합된 레이아웃을 가집니다:

backend/
 ├─ apps/
 └─ libs/

팀이 Monorepo를 사용하는 이유

• 공유 코드를 한 곳에 보관
• 프로젝트 간 리팩토링이 쉬워짐
• 툴링과 설정을 하나만 사용
• 의존성 관리가 간단해짐

마이크로서비스, 백그라운드 워커, 혹은 공유 모듈을 포함한 Nest.js 프로젝트에 monorepo는 자연스러운 선택입니다.

Nest.js Monorepo 지원 (내장)

Nest.js는 Nest CLI를 통해 일류 monorepo 지원을 제공합니다. 시작하기 위해 Nx나 Turborepo가 필요 없습니다—CLI가 하나의 워크스페이스 안에서 앱과 라이브러리를 생성할 수 있습니다.

장점

• 간단함
• 공식 지원
• 유지 관리가 쉬움

Monorepo 폴더 구조

구조는 다음과 같이 구성됩니다:

nest-monorepo/
├─ apps/
│  ├─ api/
│  └─ auth/
├─ libs/
│  ├─ common/
│  └─ database/
├─ nest-cli.json
├─ tsconfig.base.json
└─ package.json

의미

• apps/ → 실행 가능한 Nest.js 애플리케이션
• libs/ → 공유 모듈, 서비스, DTO, 헬퍼들
• common/ → 필터, 가드, 인터셉터
• database/ → Prisma, TypeORM, 혹은 기타 DB 로직

아키텍처 다이어그램

이미지 아이디어: apps/api, apps/auth와 공유 libs/common 및 libs/database를 포함하는 단일 리포지토리 박스와, 공유 사용을 나타내는 화살표들.

단계별 설정

단계 1: 새로운 Nest.js 워크스페이스 만들기

Make sure the Nest CLI is installed:

npm i -g @nestjs/cli

Create a monorepo workspace:

nest new nest-monorepo

During setup choose npm, yarn, or pnpm and optionally enable ESLint and Prettier. Nest automatically creates a workspace‑ready project.

단계 2: 모노레포 모드 활성화

Edit nest-cli.json to enable monorepo mode:

{
  "monorepo": true,
  "root": "apps/api",
  "sourceRoot": "apps/api/src",
  "projects": {}
}

Setting "monorepo": true tells Nest this repo will contain multiple apps and libraries.

단계 3: 첫 번째 앱 만들기

Generate the api app:

nest generate app api

Generate the auth app:

nest generate app auth

Resulting apps/ folder:

apps/
├─ api/
└─ auth/

Each app is a fully independent Nest.js application.

단계 4: 공유 라이브러리 만들기

Create a common library:

nest generate library common

Create a database library:

nest generate library database

Resulting libs/ folder:

libs/
├─ common/
└─ database/

Each library includes its own module, tsconfig, and clean import paths.

단계 5: 앱에 라이브러리 가져오기

Example: use CommonModule in the API app.

// apps/api/src/app.module.ts
import { Module } from '@nestjs/common';
import { CommonModule } from '@app/common';

@Module({
  imports: [CommonModule],
})
export class AppModule {}

The @app/* alias is auto‑configured by Nest, so you avoid relative‑path mess.

단계 6: 앱을 독립적으로 실행하기

Run the API app:

nest start api

Run the Auth app:

nest start auth

Each app:

• Has its own port
• Has its own environment variables
• Can be deployed separately

단계 7: 프로덕션용 빌드

Build a specific app:

nest build api

Build all apps:

nest build

Compiled output goes to the dist/ folder, separated by app name.

Nest.js 모노레포 모범 사례

• 라이브러리를 작게 유지하세요 – 각 라이브러리는 하나의 문제를 해결해야 하며, 모든 것을 common에 넣는 것을 피하세요.
• 순환 의존성을 피하세요 – 두 애플리케이션이 서로를 의존한다면 설계를 재고하세요.
• DTO와 인터페이스를 공유하세요 – 중복을 방지하고 API 일관성을 유지합니다.
• 데이터베이스 라이브러리는 하나만 – 연결을 중복하지 말고 DB 로직을 중앙화하세요.

모노레포를 사용하면 안 되는 경우

모노레포가 적합하지 않을 수 있는 경우:

• 단일 작은 서비스만 운영하는 경우
• 팀이 완전히 독립적이며 별도의 로드맵을 가지고 있는 경우
• 배포 파이프라인이 크게 다른 경우

하지만 대부분의 성장 중인 백엔드 시스템에서는 모노레포가 투자 가치가 있습니다.

최종 생각

Nest.js 모노레포는:

• 설정이 쉽다
• 공식적으로 지원된다
• 여러 서비스와 공유 코드를 위한 확장성이 있다

시도해 보고, 간소화된 개발 경험을 즐겨보세요!

추가 지원

다음 단계는?

• Nx를 추가하세요
• Medium‑style 블로그로 변환
• 실제 아키텍처 다이어그램 이미지 만들기
• Docker + monorepo 배포 추가

필요한 것이 있으면 알려 주세요.