Skip to main content
Tilnote
T
tilnote
책에 포함된 노트처음부터 배포까지, Node.js Express 서버 수업

개발 준비 운동: Node.js 설치, npm, 프로젝트 시작하기

Views 167약 9분

서버 개발은 왜 환경에서 절반이 끝날까?

서버 공부를 막 시작하면 보통 이렇게 생각합니다.

"이제 Express 배우면 끝이겠지?"

그런데 현실은 조금 다릅니다. 코드 한 줄도 안 썼는데, node 명령이 안 먹고, npm이 삐걱거리고, 프로젝트는 어디서 시작해야 할지 모르겠고, 실행 명령은 매번 까먹습니다. 서버 개발에서 의외로 많은 시간이 기능 구현이 아니라 환경이 발목을 잡지 않게 만드는 일에 들어갑니다.

그래서 이 장의 목표는 아주 분명합니다. Node.js가 제대로 설치되어 있는지 확인하고, npm으로 프로젝트를 시작하고, 패키지를 관리하고, 실행 스크립트까지 만들어서 "이제 서버 코드를 써도 되는 상태"를 만드는 것입니다.

쉽게 말해, 오늘은 헬스장 등록이 아니라 운동화 끈 묶는 날입니다. 그런데 이게 생각보다 중요합니다.

개발 준비 운동: Node.js 설치, npm, 프로젝트 시작하기

Node.js 설치: 제일 먼저 버전부터 확인하자

Node.js를 설치하면 npm도 함께 들어옵니다.1 설치 방법은 크게 두 가지입니다. 하나는 버전 관리자를 쓰는 방법이고, 다른 하나는 공식 설치 프로그램을 쓰는 방법입니다. npm 문서는 가능하면 nvm 같은 버전 관리자를 권장합니다. 버전 충돌이나 권한 문제를 줄이기 쉽기 때문입니다.1

처음 시작하는 사람이라면 이렇게 기억하면 충분합니다.

  • macOS, Linux라면 nvm 같은 버전 관리자 사용을 우선 고려한다.1

  • Windows라면 nvm-windows 같은 도구를 고려할 수 있다.1

  • 설치 프로그램으로 바로 깔아도 되지만, 그럴 때는 LTS 버전을 고르는 편이 안전하다.12

설치가 끝났다면 터미널에서 아래 명령으로 확인합니다.

node -v
npm -v

정상이라면 버전 번호가 나옵니다.

v24.14.1
10.9.0

숫자가 다르게 나와도 괜찮습니다. 중요한 건 버전이 출력되느냐입니다. 만약 command not found 같은 메시지가 뜬다면 아직 설치가 안 되었거나, 설치 후 터미널을 다시 열지 않았거나, PATH 설정이 반영되지 않은 경우가 많습니다.

어떤 버전을 깔아야 할까?

Node.js 다운로드 페이지에는 보통 LTS와 Current가 보입니다.2 초보자라면 거의 항상 LTS로 가면 됩니다.

LTS는 Long-Term Support의 줄임말입니다. 오래 지원해 주는 안정 버전이라는 뜻입니다. 서버 개발에서는 "최신 기능"보다 "문제 없이 잘 돌아감"이 더 중요할 때가 많습니다. 특히 Express를 처음 배우는 단계에서는 더 그렇습니다.

한마디로 정리하면 이렇습니다.

최신 장난감보다 검증된 공구를 들고 시작하자.

프로젝트 폴더 만들기

설치가 끝났다면 이제 작업 폴더를 만듭니다. 터미널에서 원하는 위치로 이동한 다음 새 폴더를 만드세요.

mkdir my-first-node-server
cd my-first-node-server

이제 이 폴더가 우리의 서버 프로젝트 집이 됩니다.

서버 프로젝트는 대충 아무 폴더에서 막 시작하면 나중에 파일이 흩어져서 정신이 사라집니다. 처음부터 프로젝트마다 폴더를 따로 만드는 습관이 중요합니다.

npm init: 프로젝트에 이름표 붙이기

이제 가장 중요한 첫 명령 중 하나를 실행합니다.

npm init -y

이 명령은 현재 폴더를 npm 프로젝트로 초기화하면서 package.json 파일을 만들어 줍니다.3 -y 옵션은 질문을 하나하나 묻지 않고 기본값으로 바로 진행하겠다는 뜻입니다.3

실행하고 나면 폴더 안에 이런 파일이 생깁니다.

{
  "name": "my-first-node-server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

처음 보면 조금 낯설 수 있지만, 겁먹을 필요는 없습니다. 이 파일은 프로젝트의 설명서이자 제어판입니다.

어떤 패키지를 쓰는지, 어떤 명령으로 실행하는지, 프로젝트 이름이 뭔지 같은 정보가 여기 들어갑니다. 나중에 팀원이 이 프로젝트를 받아도 package.json만 보면 어떤 준비가 필요한지 감을 잡을 수 있습니다.

package.json은 뭐 하는 파일일까?

처음에는 아래 항목만 이해해도 충분합니다.

  • name: 프로젝트 이름입니다.

  • version: 프로젝트 버전입니다.

  • main: 기본 진입 파일입니다.

  • scripts: 자주 실행할 명령어를 이름표 붙여 저장하는 곳입니다.4

  • dependencies: 실제 실행에 필요한 패키지 목록입니다.

  • devDependencies: 개발할 때만 필요한 도구 목록입니다.

여기서 특히 중요한 건 scripts입니다. 서버를 실행할 때마다 node index.js를 매번 직접 치는 것도 가능하지만, 사람은 생각보다 잘 까먹습니다. 그래서 npm start, npm run dev 같은 식으로 명령에 별명을 붙여 두는 겁니다.

이쯤 되면 package.json은 그냥 설정 파일이 아니라, 프로젝트의 리모컨처럼 느껴질 겁니다.

JavaScript 버전으로 먼저 시작하기

이 책은 먼저 JavaScript로 설명합니다. 그래서 가장 기본적인 JavaScript 프로젝트부터 만들어 보겠습니다.

루트 폴더에 index.js 파일을 만드세요.

console.log('Node.js 서버 프로젝트 준비 완료!');

아직 서버는 띄우지 않습니다. 지금은 환경 점검이 먼저입니다. 코드가 정상 실행되는지만 보겠습니다.

이제 package.json의 scripts를 이렇게 바꿔 봅시다.

{
  "name": "my-first-node-server",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "node index.js"
  }
}

그리고 실행합니다.

npm start

또는

npm run dev

start는 특별한 이름이라서 npm run start 대신 npm start로 짧게 실행할 수 있습니다.4 test도 같은 식으로 npm test가 가능합니다.4

정상이라면 터미널에 이런 문구가 나옵니다.

Node.js 서버 프로젝트 준비 완료!

여기까지 되면 최소한 다음은 확인된 것입니다.

  • Node.js가 실행된다.

  • npm 프로젝트가 정상적으로 만들어졌다.

  • package.json의 스크립트가 동작한다.

이건 별것 아닌 것 같아도, 실제로는 아주 큰 첫걸음입니다.

Express 설치: 이제 서버 공부할 준비를 하자

우리는 Express 기반 서버를 만들 예정이니, 이제 Express를 설치합니다.

npm install express

설치가 끝나면 package.json에 dependencies가 추가됩니다.

{
  "dependencies": {
    "express": "^5.1.0"
  }
}

여기서 중요한 포인트는 로컬 설치라는 점입니다. 기본적으로 npm install은 현재 프로젝트 안에 패키지를 설치합니다. 이게 좋은 이유는 프로젝트마다 필요한 버전을 따로 관리할 수 있기 때문입니다.

예를 들어 A 프로젝트는 Express 4를 쓰고, B 프로젝트는 Express 5를 써도 서로 싸우지 않습니다. 프로젝트마다 자기 방을 따로 쓰는 셈입니다.

개발 도구 설치: nodemon은 왜 필요할까?

서버 개발을 하다 보면 파일을 수정할 때마다 서버를 껐다 켜는 일이 자주 생깁니다. 처음에는 괜찮습니다.

한 번 수정하고, 한 번 종료하고, 한 번 다시 실행하고, 한숨 쉬고, 또 수정하고…

이 과정을 반복하면 금방 귀찮아집니다.

이럴 때 많이 쓰는 도구가 nodemon입니다. 파일이 바뀌면 자동으로 다시 실행해 줍니다.

npm install -D nodemon

-D는 개발 의존성으로 설치하겠다는 뜻입니다. 즉, 서비스 운영에 꼭 필요한 패키지라기보다 개발할 때 편하게 쓰는 도구라는 뜻입니다.5

이제 package.json을 이렇게 바꿔 봅시다.

{
  "name": "my-first-node-server",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  },
  "devDependencies": {
    "nodemon": "^3.1.0"
  }
}

이제 실행은 이렇게 합니다.

npm run dev

재미있는 점이 하나 있습니다. nodemon을 전역 설치하지 않아도 됩니다. npm 스크립트 안에서는 프로젝트에 설치된 실행 파일을 바로 사용할 수 있습니다.4 그래서 팀 프로젝트에서도 "내 컴퓨터엔 되는데?" 상황을 줄일 수 있습니다.

함께 생기는 파일들: node_modules와 package-lock.json

패키지를 설치하고 나면 보통 두 가지가 함께 보입니다.

하나는 node_modules 폴더이고, 다른 하나는 package-lock.json 파일입니다.

node_modules는 설치된 패키지들이 실제로 들어 있는 창고입니다. Express도, nodemon도 다 여기 들어갑니다. 폴더가 꽤 커질 수 있어서 처음 보면 놀랄 수 있습니다. "Express 하나 깔았는데 왜 이렇게 많아?" 싶은데, 패키지가 또 다른 패키지에 의존하기 때문입니다.

package-lock.json은 설치된 버전을 더 정확하게 기록하는 파일입니다. 같은 프로젝트를 다른 컴퓨터에서 설치해도 최대한 비슷하게 재현하도록 도와줍니다.

초보자에게 중요한 결론만 말하면 이렇습니다.

  • package.json은 프로젝트가 무엇을 원하나를 적는 파일

  • package-lock.json은 실제로 무엇이 설치되었나를 더 자세히 적는 파일

  • node_modules는 그 결과물이 들어 있는 폴더

추천하는 기본 스크립트 구성

서버 프로젝트는 처음부터 실행 명령을 정리해 두는 편이 좋습니다. 가장 무난한 출발점은 아래 형태입니다.

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  }
}

나중에 TypeScript를 쓰기 시작하면 보통 build도 추가됩니다. 예를 들면 이런 식입니다.

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "nodemon --watch src --ext ts --exec ts-node src/server.ts"
  }
}

스크립트 이름은 팀마다 조금 다를 수 있지만, 초보자라면 먼저 이 감각을 익히는 게 중요합니다.

  • start: 실행용

  • dev: 개발용

  • build: 빌드용

이 세 개만 잘 구분해도 프로젝트 구조가 한결 정돈됩니다.

JavaScript 기준으로 지금 만들면 좋은 최소 구조

아직은 단순하게 가겠습니다.

my-first-node-server/
├── node_modules/
├── index.js
├── package.json
└── package-lock.json

이 구조면 충분합니다. 처음부터 폴더를 열댓 개 만들 필요는 없습니다. 구조는 프로젝트가 커지면 자연스럽게 나누면 됩니다. 지금은 실행이 되는 단순한 시작점이 더 중요합니다.

TypeScript 버전으로 시작하면 어떻게 다를까?

이 책은 먼저 JavaScript로 설명하지만, TypeScript 버전도 궁금할 수 있습니다. 같은 프로젝트를 TypeScript로 준비하면 보통 개발 의존성이 조금 더 늘어납니다.5

새 폴더에서 실습한다고 가정해 보겠습니다.

mkdir my-first-node-server-ts
cd my-first-node-server-ts
npm init -y
npm install express
npm install -D typescript ts-node @types/node @types/express nodemon
npx tsc --init

여기서 각각의 역할은 이렇습니다.

  • typescript: TypeScript 컴파일러입니다.

  • ts-node: TypeScript 파일을 바로 실행할 때 도움을 줍니다.5

  • @types/node: Node.js용 타입 정보입니다.5

  • @types/express: Express용 타입 정보입니다.5

  • nodemon: 파일 변경 시 자동 재실행 도구입니다.5

TypeScript에서는 tsconfig.json도 함께 다룹니다. 아주 기본적인 형태는 이렇게 시작하면 됩니다.5

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

그리고 src/server.ts 파일을 만듭니다.

console.log('TypeScript 서버 프로젝트 준비 완료!');

package.json의 스크립트는 아래처럼 둘 수 있습니다.

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "nodemon --watch src --ext ts --exec ts-node src/server.ts"
  }
}

개발 중에는 이렇게 실행합니다.

npm run dev

배포용으로는 보통 먼저 컴파일한 뒤 실행합니다.

npm run build
npm start

즉, JavaScript와 TypeScript의 차이는 대체로 이렇습니다.

JavaScript는 바로 실행하면 되고, TypeScript는 타입 검사와 컴파일 단계가 하나 더 들어갑니다. 대신 코드가 커질수록 실수를 빨리 잡아 준다는 장점이 생깁니다.

type 필드는 왜 안 넣었을까?

package.json에는 가끔 이런 설정도 보입니다.

{
  "type": "module"
}

이 값은 import와 export를 쓰는 ES 모듈 방식과 관련이 있습니다. 반대로 이 필드가 없으면 Node.js는 기본적으로 CommonJS 방식으로 동작합니다.3

초보자 입장에서는 여기서 바로 모듈 시스템까지 깊게 들어가면 머리가 바빠집니다. 그래서 이 장에서는 복잡도를 낮추기 위해 기본 흐름만 익히는 데 집중하겠습니다.

지금 중요한 건 "어떤 모듈 방식이 더 멋진가"가 아니라, 프로젝트를 만들고 실행하는 감각을 익히는 것입니다.

자주 헷갈리는 명령, 한 번에 정리

여기서 지금까지 쓴 명령을 다시 정리해 보겠습니다.

# 버전 확인
node -v
npm -v

# 프로젝트 시작
npm init -y

# 패키지 설치
npm install express
npm install -D nodemon

# JavaScript 실행
npm start
npm run dev

TypeScript까지 포함하면 다음도 추가됩니다.

npm install -D typescript ts-node @types/node @types/express nodemon
npx tsc --init
npm run build
npm start
npm run dev

이 명령들이 손에 익기 시작하면, 서버 개발의 시작이 훨씬 부드러워집니다.

초보자가 자주 막히는 세 가지

환경 설정에서 자주 만나는 문제는 의외로 비슷합니다.

  • node -v가 안 된다면 설치가 안 되었거나 터미널 재시작이 필요할 수 있습니다.

  • npm 권한 문제가 난다면 설치 프로그램 대신 버전 관리자를 쓰는 쪽이 더 편할 때가 많습니다.1

  • Cannot find module 'express'가 뜬다면 현재 폴더가 프로젝트 루트인지, 그리고 npm install express를 정말 그 폴더에서 했는지 확인해야 합니다.

이런 문제는 실력이 부족해서 생긴다기보다, 아직 개발 환경이 덜 정리되어 있어서 생기는 경우가 많습니다. 너무 위축될 필요 없습니다. 서버 개발자는 코드만 쓰는 사람이 아니라, 실행 환경도 다루는 사람입니다.

지금 단계의 추천 체크리스트

이 장을 끝내기 전에 아래 항목을 직접 확인해 보세요.

  • node -v와 npm -v가 정상 출력된다.

  • 새 폴더에서 npm init -y로 package.json을 만들 수 있다.

  • npm install express로 의존성을 추가할 수 있다.

  • npm install -D nodemon으로 개발 도구를 추가할 수 있다.

  • package.json에 start, dev 스크립트를 넣고 실행할 수 있다.

  • JavaScript 버전과 TypeScript 버전의 준비 차이를 설명할 수 있다.

이 체크리스트를 통과했다면, 이제 여러분의 컴퓨터는 "서버 공부 구경꾼"이 아니라 "서버 개발 작업대"가 된 것입니다.

마무리

이번 장에서는 화려한 API도, 멋진 라우팅도 만들지 않았습니다. 대신 더 중요한 걸 했습니다.

Node.js를 설치하고, npm 프로젝트를 시작하고, 패키지를 설치하고, 실행 스크립트를 만들었습니다. 이 과정은 겉보기엔 단순하지만, 이후의 모든 서버 개발이 기대고 서 있는 바닥입니다.

서버 개발의 절반은 환경에서 안 막히는 것부터 시작합니다. 그리고 이제, 여러분은 그 절반을 꽤 든든하게 지나왔습니다.

참고

1Downloading and installing Node.js and npm

2Node.js — Download Node.js®

3npm init - GeeksforGeeks

4scripts  npm Docs

5How to set up TypeScript with Node.js and Express

책 목록

처음부터 배포까지, Node.js Express 서버 수업

전체 목차 보기

이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.

틸노트는 사용자가 AI를 활용해 노트를 쉽게 작성하거나 편집할 수 있는 서비스입니다.

회원 가입

AI 스퀘어 단톡방에 함께해요

AI 활용과 틸노트 사용 팁을 나누는 오픈채팅방입니다. 입장 비밀번호는 tilnote입니다.

참여하기
이용약관·개인정보처리방침