npm run dev를 치면 무슨 일이 일어나나
바이브 코딩으로 웹을 만들다 보면 누구나 똑같은 데서 처음 막힌다. 코드는 짰는데 이걸 대체 어디서 보는지 모르는 순간이다. 답은 인터넷에 올리는 배포가 아니라 내 컴퓨터 안에서 먼저 띄우는 것이고, 그 시작이 npm run dev 한 줄이다. 프로젝트 폴더에서 터미널을 열고 이 명령을 치면 개발 서버(dev server)가 켜진다.
개발 서버는 내가 짠 코드를 웹페이지로 바꿔 실시간으로 보여 주는 프로그램이다. 명령을 치면 몇 초 뒤 터미널에 주소 한 줄이 뜬다 — 'Local: http://localhost:3000'. 이 주소를 브라우저 주소창에 그대로 넣으면 방금 만든 화면이 바로 나타난다. 코드를 고치고 저장하면 새로고침을 안 해도 화면이 즉시 바뀌는데, 개발 서버가 파일 변경을 감지해 다시 그려 주기 때문이다. 만들면서 곧바로 확인하기 좋은 이유다.
localhost:3000은 어디를 가리키나
localhost는 남의 서버 주소가 아니라 지금 이 명령을 친 내 컴퓨터 자신을 가리키는 이름이다. 숫자로는 127.0.0.1이고, 어떤 컴퓨터에서 치든 언제나 '그 컴퓨터 자기 자신'을 뜻한다. 그래서 localhost로 띄운 화면은 인터넷에 올라간 게 아니라 내 기계 안에서만 돌고, 같은 네트워크의 남에게도 기본적으로는 보이지 않는다.
뒤에 붙은 3000은 포트(port) 번호다. 컴퓨터라는 건물에 방(문)이 여러 개 있고, 이 앱이 그중 3000호를 쓰고 있다는 뜻이다. 한 컴퓨터에서 여러 앱을 동시에 띄워도 서로 다른 방 번호를 쓰면 섞이지 않는다. 기본 번호는 도구마다 다르다 — Next.js·React 계열은 3000, 다른 도구는 5173이나 8000을 쓰기도 한다. 외울 필요는 없고, 터미널에 뜬 주소를 그대로 따라가면 된다.
npm은 무엇이고 package.json은 무슨 역할인가
npm은 이 명령을 굴려 주는 도구다. 이름은 Node Package Manager의 줄임으로, 자바스크립트 프로젝트에서 필요한 부품(패키지)을 내려받고 정해진 명령을 실행해 주는 관리자 역할을 한다. 자바스크립트를 컴퓨터에서 돌리는 실행 환경인 Node.js를 설치하면 npm도 함께 깔리므로, 따로 설치할 것은 대개 없다.
프로젝트 폴더 안에는 package.json이라는 파일이 있다. 이 파일에 이 프로젝트가 쓰는 부품 목록과, 'dev'·'build'·'start' 같은 실행 이름(scripts)이 적혀 있다. 각 이름에는 실제로 돌릴 진짜 명령이 연결돼 있다 — 예를 들어 'dev'에 'next dev'가 연결돼 있으면, npm run dev를 칠 때 npm이 그 'next dev'를 대신 찾아 실행한다.
이 구조 덕분에 도구마다 실제 명령이 달라도 사람은 npm run dev 하나만 외우면 된다. 다만 처음 받아 온 프로젝트라면 순서가 하나 더 있다 — npm install을 먼저 친다. 이건 package.json에 적힌 부품들을 인터넷에서 내려받아 node_modules 폴더에 채워 넣는 명령이다. 부품이 없으면 서버가 안 켜지므로, 새 프로젝트는 install이 먼저다.
처음부터 끝까지 — 세 명령의 순서
정리하면 순서는 늘 셋이다. ① npm install로 부품을 채우고 ② npm run dev로 내 컴퓨터에 개발 서버를 띄우고 ③ 브라우저 주소창에 localhost:3000을 넣어 확인한다.
아래는 npm run dev를 쳤을 때 터미널에 실제로 뜨는 화면과, 그 명령이 어디서 정의됐는지 보여 주는 package.json의 scripts 부분이다. 확인이 끝나고 서버를 멈추려면 터미널에서 Ctrl+C를 누른다. 인터넷에 공개하는 배포는 이 모든 게 내 컴퓨터에서 잘 도는 것을 확인한 다음 이야기다.
➜ my-app npm run dev
> my-app@0.1.0 dev
> next dev
▲ Next.js 16.2.10 (Turbopack)
- Local: http://localhost:3000
- Network: http://192.168.0.10:3000
✓ Ready in 293ms{
"name": "my-app",
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}자주 막히는 곳
'포트가 이미 쓰이고 있다(port already in use)'는 메시지가 뜨면, 3000호를 다른 프로그램이 이미 쓰고 있다는 뜻이다. 앞서 띄운 서버를 Ctrl+C로 끄지 않았을 때 흔히 난다. 대개는 도구가 3001처럼 다른 번호로 알아서 옮겨 띄우니, 터미널에 새로 뜬 주소를 그대로 따라가면 된다.
명령을 쳤는데 'command not found'가 뜨면 Node.js가 아직 안 깔린 것이다. nodejs.org에서 설치하면 npm도 함께 들어온다. '그런 스크립트가 없다'는 오류는 package.json의 scripts에 그 이름이 없다는 뜻이니, dev 대신 start처럼 실제 적힌 이름을 확인한다. 그리고 화면이 아예 안 뜨면 npm install을 빼먹지 않았는지 가장 먼저 본다.