개발/NestJS

NestJS 마스터 시리즈 2화. 프로젝트 초기 설정 – CLI로 구조를 잡아보자

B컷개발자 2025. 4. 26. 13:31
728x90
SMALL

“디렉토리 구조를 이해하면 절반은 먹고 들어간다”

 

NestJS 프로젝트를 Nest CLI로 설정하는 방법과 디렉토리 구조, main.ts, app.module.ts의 역할까지 실무 관점에서 깊이 있게 분석합니다. 초보 개발자도 쉽게 따라할 수 있는 프로젝트 설정 가이드입니다.

 

 

🏁 시작부터 구조가 중요하다

 

NestJS는 단순히 코드 몇 줄로 시작하는 Express와는 다릅니다.

NestJS는 아키텍처 기반 프레임워크이며, 설계 관점에서 접근해야 합니다.

 

그 시작점은 바로 **Nest CLI(Command Line Interface)**입니다.

 

“Nest CLI 없이 Nest 프로젝트를 시작하는 건, 설계도 없이 건축을 시작하는 것과 같다.”

 

 

🧰 NestJS 프로젝트 생성하기

 

 

1단계: Nest CLI 설치

npm install -g @nestjs/cli

 

2단계: 새 프로젝트 생성

nest new my-nest-app

 

  • my-nest-app은 원하는 프로젝트 이름으로 변경 가능합니다.
  • 설치 중 npm 또는 yarn 선택 가능 (회사 정책에 따라 결정)

 

 

3단계: 프로젝트 디렉토리 이동

cd my-nest-app

 

 

 

🧱 NestJS 기본 디렉토리 구조 분석

 

Nest CLI로 생성된 구조는 다음과 같습니다:

src/
  ├── app.controller.ts       // 라우팅 담당
  ├── app.controller.spec.ts  // 컨트롤러 테스트
  ├── app.module.ts           // 루트 모듈
  ├── app.service.ts          // 서비스 로직
  └── main.ts                 // 앱 진입점

각 파일의 의미는 다음과 같습니다:

파일명역할

main.ts Nest 앱의 진입점 (서버 구동)
app.module.ts 앱의 루트 모듈, 모든 구성 요소를 여기에 연결
app.controller.ts 라우터 역할을 하는 컨트롤러
app.service.ts 비즈니스 로직 담당
*.spec.ts 단위 테스트 파일 (Jest 기반)

 

 

 

🔍 핵심 파일 1 – 

main.ts

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

 

  • NestFactory.create()는 루트 모듈(AppModule)을 불러와 Nest 애플리케이션 인스턴스를 만듭니다.
  • app.listen(3000)은 서버를 포트 3000번에서 시작시킵니다.

 

👉 이 코드는 백엔드의 앱 실행 entry point이며, 추후 미들웨어나 글로벌 설정을 여기서 구성하게 됩니다.

 

 

🔍 핵심 파일 2 – 

app.module.ts

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

 

  • @Module() 데코레이터는 이 모듈이 사용하는 컨트롤러와 프로바이더(Service)를 정의합니다.
  • 여기에 다른 모듈을 import해서 전체 앱을 구성하게 됩니다.

 

Nest의 철학은 “모듈 중심 구조”입니다. app.module.ts는 모든 기능의 루트 노드 역할을 합니다.

 

 

🚧 실무 기준으로 구조 확장 팁

 

Nest CLI의 기본 구조는 학습에는 좋지만, 실무에서는 보통 다음처럼 확장합니다:

src/
  ├── main.ts
  ├── app.module.ts
  ├── common/           // 공통 모듈, 인터셉터, 필터, 유틸 등
  ├── config/           // 환경 설정 및 .env 연동
  ├── modules/          // 기능별 모듈 집합 (User, Auth 등)
  └── shared/           // 인터페이스, 상수, 공통 DTO 등

이 구조를 초반에 잡아두면 확장성과 유지보수성이 확실히 올라갑니다.

 

 

✅ 개발자 팁 – Git 초기화 및 설정

git init
echo "node_modules" > .gitignore

 

  • .gitignore 설정은 nest new 시 자동으로 생성되지만, 팀 환경에서는 공통 템플릿을 사용하는 것이 좋습니다.
  • 이후 husky, eslint, prettier 같은 설정도 초기에 잡아두면 협업 시 큰 도움이 됩니다.

 

 

🔚 마무리 인사이트

 

NestJS는 CLI 단계에서부터 구조화된 개발 철학을 강요합니다.

그 철학을 이해하고 따라가는 것이 유지보수성과 확장성 있는 서비스를 만드는 첫걸음입니다.

 

구조는 귀찮은 게 아니라, 개발의 가장 강력한 무기입니다.

 

 

📎 다음 회차 예고

 

👉 3화. 모듈 시스템 이해하기 – Nest의 핵심 철학 ‘모듈화’ 분석

 

AppModule을 이해하면 NestJS 전체 구조가 보입니다. 실제 기능별 모듈로 확장하는 방법까지 정리합니다.
728x90
LIST