개발 환경 설정
Node.js와 패키지 관리자를 준비하고 Nest CLI로 프로젝트를 생성해 개발 서버의 실행 결과까지 확인합니다.
NestJS의 특징과 아키텍처를 확인했으니, 이제 NestJS 개발 환경을 직접 설정합니다.
환경 준비는 명령어를 외우는 일이 아니라 런타임, 패키지 관리자, CLI, 프로젝트, HTTP 응답의 경계를 차례로 통과하는 과정입니다.
NestJS 개발 환경 준비와 실패 경계
runtime·package manager·CLI·scaffold·첫 HTTP 응답에서 산출물과 통과 증거가 단계마다 바뀐다.
Nest 환경 · 단계별 통과 신호
런타임부터 첫 HTTP 응답까지, 막힌 경계를 순서대로 확인합니다
프로젝트 생성용 CLI 실행 방식은 하나를 선택합니다. 생성 후 start:dev는 프로젝트의 로컬 CLI를 사용하며, 로그 문구보다 설정된 포트의 실제 응답을 확인합니다.
Node.js와 패키지 관리자를 확인한 뒤 전역 nest 또는 npx 생성 CLI 하나를 선택한다. scaffold가 만든 프로젝트와 의존성은 start:dev의 입력이며, 생성 후에는 프로젝트 로컬 CLI가 실제 HTTP 응답까지 실행한다.
관계도 해설과 예제 원자료
| 경계 | 확인 · 실행 | 통과 신호 | 막히면 먼저 볼 곳 |
|---|---|---|---|
| Node.js 런타임 | node --version |
Nest와 CLI의 최소 요구를 만족하는 현재 지원 중인 LTS를 사용한다. | Node.js release status, 설치 경로, 새로 연 shell의 PATH |
| 패키지 관리자 | npm --version |
선택한 도구가 실행되고 프로젝트에서는 한 종류의 lockfile을 유지한다. | Node.js·npm 설치, shell 재시작, 팀이 정한 npm·Yarn·pnpm 기준 |
| Nest CLI |
또는 |
new 등 CLI 명령 도움말을 확인한다. |
전역 설치 권한·버전·binary 경로 또는 npx의 네트워크 접근 |
| 프로젝트 scaffold |
또는 |
프로젝트 폴더, package.json, src/와 설치된 의존성이 생긴다. |
생성 위치의 쓰기 권한, 네트워크, 선택한 패키지 관리자 |
| 개발 서버와 첫 응답 | npm run start:dev |
애플리케이션이 설정된 포트에서 요청을 받고 기본 route가 응답한다. | package.json이 있는 현재 폴더, 터미널 예외, 포트 충돌, route 경로 |
- 1. Node.js 런타임
- 확인
node --version - 통과 Nest와 CLI 최소 요구를 만족하는 현재 지원 중인 LTS다.
- 진단 release status, 설치 경로, 새 shell의
PATH를 본다. - 2. 패키지 관리자
- 확인 교재 기준은
npm --version이다. - 통과 선택한 도구가 실행되고 lockfile을 한 종류로 유지한다.
- 진단 Node.js·npm 설치와 팀의 npm·Yarn·pnpm 기준을 확인한다.
- 3. Nest CLI
- 확인
nest --help또는npx @nestjs/cli@latest --help - 통과
new등 명령 도움말이 나온다. - 진단 전역 설치의 권한·버전·경로 또는
npx네트워크를 본다. - 4. 프로젝트 scaffold
- 실행
nest new my-nestjs-app또는npx @nestjs/cli@latest new my-nestjs-app - 통과 프로젝트 폴더,
package.json,src/와 의존성이 생긴다. - 진단 생성 위치 권한, 네트워크, 패키지 관리자 선택을 본다.
- 5. 개발 서버와 첫 응답
- 실행 프로젝트 폴더에서
npm run start:dev - 통과 설정된 포트의 기본 route가 응답한다.
- 진단 현재 폴더, 터미널 예외, 포트 충돌, route 경로를 본다.
start:dev script는 프로젝트에 설치된 Nest CLI를 사용한다. 정확한 로그 문구보다 어느 경계까지 통과했는지를 확인한다.이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
관계도의 보충 설명
| 순번 | 원문 표시 |
|---|---|
| 1 | NestJS 개발 환경 준비와 실패 경계 |
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 도구 경계 확인 Node·패키지 관리자·선택 CLI의 실행을 확인합니다. | 증거: version·help · CLI: 한 방식 선택 | 프로젝트 생성 전 도구를 확인합니다. |
| scaffold 산출물 new가 프로젝트 폴더·package.json·src·의존성을 만듭니다. | 산출물: 프로젝트·의존성 · lockfile: 한 종류 | 개발 실행의 입력이 생깁니다. |
| 첫 HTTP 확인 start:dev의 로컬 CLI로 실행하고 설정 포트의 응답을 확인합니다. | 실행: 프로젝트 local CLI · 증거: 실제 HTTP 응답 | 로그 문구보다 마지막 실행 경계를 확인합니다. |
NestJS 개발 환경 준비와 실패 경계
runtime·package manager·CLI·scaffold·첫 HTTP 응답에서 산출물과 통과 증거가 단계마다 바뀐다.
Nest 환경 · 단계별 통과 신호
런타임부터 첫 HTTP 응답까지, 막힌 경계를 순서대로 확인합니다
프로젝트 생성용 CLI 실행 방식은 하나를 선택합니다. 생성 후 start:dev는 프로젝트의 로컬 CLI를 사용하며, 로그 문구보다 설정된 포트의 실제 응답을 확인합니다.
Node.js와 패키지 관리자를 확인한 뒤 전역 nest 또는 npx 생성 CLI 하나를 선택한다. scaffold가 만든 프로젝트와 의존성은 start:dev의 입력이며, 생성 후에는 프로젝트 로컬 CLI가 실제 HTTP 응답까지 실행한다.
관계도 해설과 예제 원자료
| 경계 | 확인 · 실행 | 통과 신호 | 막히면 먼저 볼 곳 |
|---|---|---|---|
| Node.js 런타임 | node --version |
Nest와 CLI의 최소 요구를 만족하는 현재 지원 중인 LTS를 사용한다. | Node.js release status, 설치 경로, 새로 연 shell의 PATH |
| 패키지 관리자 | npm --version |
선택한 도구가 실행되고 프로젝트에서는 한 종류의 lockfile을 유지한다. | Node.js·npm 설치, shell 재시작, 팀이 정한 npm·Yarn·pnpm 기준 |
| Nest CLI |
또는 |
new 등 CLI 명령 도움말을 확인한다. |
전역 설치 권한·버전·binary 경로 또는 npx의 네트워크 접근 |
| 프로젝트 scaffold |
또는 |
프로젝트 폴더, package.json, src/와 설치된 의존성이 생긴다. |
생성 위치의 쓰기 권한, 네트워크, 선택한 패키지 관리자 |
| 개발 서버와 첫 응답 | npm run start:dev |
애플리케이션이 설정된 포트에서 요청을 받고 기본 route가 응답한다. | package.json이 있는 현재 폴더, 터미널 예외, 포트 충돌, route 경로 |
- 1. Node.js 런타임
- 확인
node --version - 통과 Nest와 CLI 최소 요구를 만족하는 현재 지원 중인 LTS다.
- 진단 release status, 설치 경로, 새 shell의
PATH를 본다. - 2. 패키지 관리자
- 확인 교재 기준은
npm --version이다. - 통과 선택한 도구가 실행되고 lockfile을 한 종류로 유지한다.
- 진단 Node.js·npm 설치와 팀의 npm·Yarn·pnpm 기준을 확인한다.
- 3. Nest CLI
- 확인
nest --help또는npx @nestjs/cli@latest --help - 통과
new등 명령 도움말이 나온다. - 진단 전역 설치의 권한·버전·경로 또는
npx네트워크를 본다. - 4. 프로젝트 scaffold
- 실행
nest new my-nestjs-app또는npx @nestjs/cli@latest new my-nestjs-app - 통과 프로젝트 폴더,
package.json,src/와 의존성이 생긴다. - 진단 생성 위치 권한, 네트워크, 패키지 관리자 선택을 본다.
- 5. 개발 서버와 첫 응답
- 실행 프로젝트 폴더에서
npm run start:dev - 통과 설정된 포트의 기본 route가 응답한다.
- 진단 현재 폴더, 터미널 예외, 포트 충돌, route 경로를 본다.
start:dev script는 프로젝트에 설치된 Nest CLI를 사용한다. 정확한 로그 문구보다 어느 경계까지 통과했는지를 확인한다.이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
관계도의 보충 설명
| 순번 | 원문 표시 |
|---|---|
| 1 | NestJS 개발 환경 준비와 실패 경계 |
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 도구 경계 확인 Node·패키지 관리자·선택 CLI의 실행을 확인합니다. | 증거: version·help · CLI: 한 방식 선택 | 프로젝트 생성 전 도구를 확인합니다. |
| scaffold 산출물 new가 프로젝트 폴더·package.json·src·의존성을 만듭니다. | 산출물: 프로젝트·의존성 · lockfile: 한 종류 | 개발 실행의 입력이 생깁니다. |
| 첫 HTTP 확인 start:dev의 로컬 CLI로 실행하고 설정 포트의 응답을 확인합니다. | 실행: 프로젝트 local CLI · 증거: 실제 HTTP 응답 | 로그 문구보다 마지막 실행 경계를 확인합니다. |
Node.js와 패키지 관리자 준비
NestJS 애플리케이션은 Node.js에서 실행됩니다. Node.js와 npm을 설치한 뒤 먼저 터미널에서 두 명령이 동작하는지 확인합니다.
node --version
npm --versionNest 애플리케이션과 CLI 생성 명령은 요구하는 Node.js 버전 범위가 다를 수 있습니다. Nest 공식 시작 문서의 두 요구사항을 모두 확인하세요. 새 환경에는 Node.js 릴리스 표에서 Active LTS로 표시되고 두 요구사항을 만족하는 버전을 선택하는 것이 좋습니다. 기존 환경도 최소 버전과 현재 유지보수 여부를 별도로 확인하세요.
설치는 Node.js 다운로드 페이지 또는 운영체제에 맞는 버전 관리자를 사용합니다. npm 설치 문서도 Node.js와 npm을 함께 설치하고 관리할 수 있는 버전 관리자를 권장합니다.
이 교재의 명령은 npm을 기준으로 합니다. nest new에서 Yarn이나 pnpm을 선택할 수도 있지만, 한 프로젝트에서는 팀이 정한 패키지 관리자와 lockfile을 일관되게 사용하세요.
Yarn은 더 이상 npm install -g yarn을 기본 설치법으로 안내하지 않습니다. Yarn이나 pnpm을 선택한다면 고정된 전역 설치 예제를 따르기보다 각 도구의 현행 설치 문서를 확인하세요.
Nest CLI 준비
Nest CLI는 프로젝트 scaffold, component 생성, 개발 실행과 build 명령을 제공합니다. CLI를 실행하는 방법은 두 가지이며, 아래 방법 중 하나를 선택합니다.
전역 CLI
Nest 공식 가이드가 기본 흐름으로 사용하는 방법입니다.
npm install --global @nestjs/cli
nest --help전역 설치는 nest 명령을 어디서나 바로 쓸 수 있어 편리하지만, 어떤 CLI 버전을 실행하는지는 사용자가 관리해야 합니다.
전역 설치 없는 실행
Nest CLI 문서는 npx를 관리형 대안으로 안내합니다.
npx @nestjs/cli@latest --help프로젝트 생성 때도 같은 접두사를 사용하면 됩니다. 전역 nest와 npx 명령을 연달아 실행할 필요는 없습니다.
첫 NestJS 프로젝트 생성
프로젝트를 만들 상위 디렉터리에서 선택한 CLI 실행 방식에 맞는 명령 하나를 실행합니다.
전역 CLI를 설치했다면:
nest new my-nestjs-app전역 설치 없이 실행한다면:
npx @nestjs/cli@latest new my-nestjs-appCLI는 사용할 패키지 관리자를 묻고, 선택을 마치면 프로젝트 폴더와 설정 파일, src/의 기본 파일을 만들고 의존성을 설치합니다. 질문의 정확한 문구나 생성 로그 형식은 CLI 버전에 따라 달라질 수 있으므로 교재 예시와 한 글자씩 비교하지 않아도 됩니다.
현재 공식 First Steps는 새 프로젝트에서 TypeScript strict 설정을 기본으로 활성화한다고 안내합니다. --strict 옵션이 필요한지는 사용한 CLI 버전과 생성된 tsconfig.json을 확인합니다.
이 교재의 이후 예제는 Nest 11의 CommonJS 구성을 기준으로 설명합니다. @latest는 실행 시점의 최신 CLI를 사용하므로, 생성된 모듈 형식과 설정이 교재의 파일 표기와 다를 수 있습니다.
교재의 Nest 11 예제를 재현하려면 위의 최신 생성 명령 대신 npx @nestjs/cli@11 new my-nestjs-app을 사용합니다. 프로젝트를 두 번 만들라는 뜻은 아닙니다. 생성 후 프로젝트 폴더에서 npm ls @nestjs/core @nestjs/common @nestjs/cli로 실제 설치된 주버전을 확인하고 lockfile을 보존하세요. 최신 Nest를 배우려는 경우에는 @latest 경로를 선택하고 공식 마이그레이션 안내로 교재와의 차이를 확인합니다. CommonJS를 선택하는 것만으로 Nest의 주버전이 11로 고정되지는 않습니다.
현재 공식 시작 문서의 CLI는 모듈 형식을 선택하게 하며, ESM은 Vitest, CommonJS는 Jest를 사용하는 구성을 안내합니다. 이 교재의 확장자 없는 상대 import와 Jest 테스트를 그대로 따라가려면 생성 질문에서 CommonJS를 선택하세요. ESM을 선택했다면 ./app.module.js 같은 import 표기와 테스트 도구도 생성된 설정에 맞춰야 합니다. 두 방식의 파일을 섞기 전에 package.json과 tsconfig.json을 확인합니다.
NestJS Observe 연동을 묻는 질문이 나오면 이 첫 응답 실습에서는 No를 선택합니다. 관측 SDK와 앱 키·시크릿 연결은 첫 Hello World! 응답에 필요하지 않습니다. 관측 기능을 선택한 프로젝트는 공식 관측 문서에 따라 그 설정을 별도로 준비해야 합니다.
프로젝트 실행 및 확인
생성된 프로젝트 폴더로 이동해 개발 script를 실행합니다.
cd my-nestjs-app
npm run start:devstart:dev는 생성된 package.json의 script이며 프로젝트에 설치된 로컬 Nest CLI를 사용합니다. 파일 변경을 감시하고 애플리케이션을 다시 컴파일해 재실행하므로, 프로젝트 생성에 사용한 전역 CLI와 개발 서버의 실행 경계를 구분해야 합니다.
고정된 날짜, 프로세스 ID, 로그 문구 대신 다음 상태를 확인하세요.
- 명령을
package.json이 있는 프로젝트 폴더에서 실행했는가 - 터미널에 처리되지 않은 예외 없이 애플리케이션이 HTTP 요청을 기다리는가
src/main.ts에 정의된 포트와 브라우저에서 연 포트가 같은가
기본 scaffold를 바꾸지 않았다면 http://localhost:3000/에서 Hello World! 응답을 확인할 수 있습니다. main.ts나 환경 변수로 포트를 바꿨다면 해당 포트로 접속해야 합니다.
Nest 개발 서버에서 첫 HTTP 응답까지
프로젝트 script·로컬 CLI watch·main listener·브라우저 route 응답의 실제 실행 경계이다.
Nest 개발 실행 · 로컬 CLI와 HTTP
프로젝트 script가 로컬 CLI를 실행하고, listener의 응답을 확인합니다
package.json이 있는 폴더에서 시작합니다. Nest CLI가 watch·컴파일·재실행을 맡고, main.ts가 정한 포트와 controller route가 브라우저 주소의 기준이 됩니다.
- 프로젝트 폴더 확인
package.json과src/main.ts가 있는 생성된 앱 폴더로 이동한다. - 개발 script 실행
npm run start:dev는 프로젝트에 설치된 로컬 Nest CLI를 호출한다. - 애플리케이션 부팅
Nest CLI가 변경을 감시하고 다시 컴파일하며,
main.ts에 정의된 포트에서 HTTP 요청을 기다린다. - HTTP 응답 확인
브라우저에서 설정된 포트의 기본 route를 열어 응답을 확인한다.
package.json, 부팅하지 못하면 터미널 예외와 포트, 부팅했지만 응답이 다르면 URL과 controller route를 확인한다.이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
- package.json이 있는 프로젝트 폴더에서 start:dev script를 실행하면 프로젝트의 로컬 Nest CLI가 애플리케이션을 감시하고 다시 컴파일해 실행한다. main.ts의 HTTP listener가 설정된 포트에서 브라우저 요청을 받아 기본 route 응답을 반환한다.
- 프로젝트의 package.json 스크립트가 로컬 Nest CLI를 실행한다. CLI가 컴파일과 감시를 맡고 main.ts가 정한 리스너로 요청을 보내 응답을 확인한다.
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 프로젝트 script package.json 폴더에서 start:dev를 실행합니다. | 입력: 프로젝트 script · CLI: local Nest | 프로젝트 도구가 개발 실행을 시작합니다. |
| watch·listen CLI가 다시 컴파일·실행하고 main listener를 엽니다. | 상태: watch·컴파일 · listener: 설정 포트 | 브라우저 요청을 받을 준비가 됩니다. |
| 기본 route 응답 브라우저 요청에 기본 route가 응답합니다. | 증거: HTTP 응답 · 대상: 기본 route | 개발 실행이 실제 요청까지 도달합니다. |
Nest 개발 서버에서 첫 HTTP 응답까지
프로젝트 script·로컬 CLI watch·main listener·브라우저 route 응답의 실제 실행 경계이다.
Nest 개발 실행 · 로컬 CLI와 HTTP
프로젝트 script가 로컬 CLI를 실행하고, listener의 응답을 확인합니다
package.json이 있는 폴더에서 시작합니다. Nest CLI가 watch·컴파일·재실행을 맡고, main.ts가 정한 포트와 controller route가 브라우저 주소의 기준이 됩니다.
- 프로젝트 폴더 확인
package.json과src/main.ts가 있는 생성된 앱 폴더로 이동한다. - 개발 script 실행
npm run start:dev는 프로젝트에 설치된 로컬 Nest CLI를 호출한다. - 애플리케이션 부팅
Nest CLI가 변경을 감시하고 다시 컴파일하며,
main.ts에 정의된 포트에서 HTTP 요청을 기다린다. - HTTP 응답 확인
브라우저에서 설정된 포트의 기본 route를 열어 응답을 확인한다.
package.json, 부팅하지 못하면 터미널 예외와 포트, 부팅했지만 응답이 다르면 URL과 controller route를 확인한다.이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
- package.json이 있는 프로젝트 폴더에서 start:dev script를 실행하면 프로젝트의 로컬 Nest CLI가 애플리케이션을 감시하고 다시 컴파일해 실행한다. main.ts의 HTTP listener가 설정된 포트에서 브라우저 요청을 받아 기본 route 응답을 반환한다.
- 프로젝트의 package.json 스크립트가 로컬 Nest CLI를 실행한다. CLI가 컴파일과 감시를 맡고 main.ts가 정한 리스너로 요청을 보내 응답을 확인한다.
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 프로젝트 script package.json 폴더에서 start:dev를 실행합니다. | 입력: 프로젝트 script · CLI: local Nest | 프로젝트 도구가 개발 실행을 시작합니다. |
| watch·listen CLI가 다시 컴파일·실행하고 main listener를 엽니다. | 상태: watch·컴파일 · listener: 설정 포트 | 브라우저 요청을 받을 준비가 됩니다. |
| 기본 route 응답 브라우저 요청에 기본 route가 응답합니다. | 증거: HTTP 응답 · 대상: 기본 route | 개발 실행이 실제 요청까지 도달합니다. |
막힌 위치를 스스로 찾아보기
node --version과 CLI 도움말은 정상인데, npm run start:dev에서 package.json을 찾을 수 없다고 나옵니다. Node.js를 다시 설치하기 전에 무엇을 확인해야 할까요? 반대로 서버 시작 로그가 나온 뒤 브라우저에서 연결할 수 없다면 무엇을 비교해야 할까요?
확인 순서와 이유
첫 경우에는 생성된 my-nestjs-app 폴더로 이동했는지 확인합니다. npm은 현재 프로젝트의 스크립트를 실행하므로 CLI 설치가 정상이어도 다른 폴더에서는 그 스크립트를 찾지 못합니다. 두 번째 경우에는 main.ts의 포트, PORT 환경 변수, 브라우저 주소를 비교하고 서버 프로세스가 계속 실행 중인지 확인합니다. 로그를 한 번 보았다는 사실만으로 현재 HTTP 응답까지 확인한 것은 아닙니다.
Node.js와 패키지 관리자, Nest CLI, 첫 프로젝트 생성, 개발 서버의 HTTP 응답까지 확인했습니다.
다음 절에서는 생성된 모듈, 컨트롤러, 서비스가 요청 처리 흐름에서 맡는 책임을 살펴봅니다.