Cursor나 Claude Code 같은 AI 코딩 도구로 웹서비스를 만들다 보면 생각보다 빠르게 Node.js, npm, package.json이라는 용어를 만나게 됩니다.
AI가 코드를 만들어주는 시대라고 해도 이 세 가지가 어떤 역할을 하는지 전혀 모르면 프로젝트 설치나 실행 단계에서 쉽게 막힐 수 있습니다.
이번 글에서는 코딩을 처음 시작한 사람도 npm이 무엇인지, Node.js와 어떤 관계인지, package.json은 왜 필요한지를 이해할 수 있도록 실제 바이브코딩 과정과 연결해서 알아보겠습니다.
1. npm은 왜 알아야 할까?
바이브코딩을 하다 보면 AI가 코드를 작성하는 것보다 먼저 프로젝트에 필요한 도구를 설치하는 과정이 등장합니다.
예를 들어 AI에게 “Next.js로 로그인 페이지를 만들어줘”라고 요청했다고 생각해보겠습니다.
AI는 필요한 코드를 작성하면서 다음과 같은 명령어를 알려줄 수 있습니다.
npm install또는 특정 기능을 추가하면서 다음처럼 말할 수도 있습니다.
npm install axios처음 보는 사람 입장에서는 “코드를 만들어달라고 했는데 왜 갑자기 npm을 설치하라고 하지?” 라는 생각이 들 수 있습니다.
쉽게 말하면 npm은 프로젝트에 필요한 여러 개발 도구와 기능을 가져와서 사용할 수 있도록 도와주는 패키지 관리자입니다.
바이브코딩에서 npm을 직접 깊게 공부할 필요는 없습니다.
하지만 패키지를 설치하고 프로젝트를 실행하기 위해 사용하는 도구라는 정도는 반드시 알고 있어야 합니다.
2. Node.js란?
npm을 이해하려면 먼저 Node.js를 알아야 합니다.
JavaScript는 원래 웹브라우저에서 동작하는 언어로 많이 사용됐습니다. 우리가 웹사이트에서 버튼을 클릭하거나, 화면의 내용이 바뀌거나, 사용자 입력에 반응하는 기능 등이 대표적입니다.
그런데 Node.js를 이용하면 JavaScript를 브라우저 밖에서도 실행할 수 있습니다.
쉽게 비유하면 JavaScript가 하나의 요리 레시피라면, Node.js는 그 레시피를 실제로 실행할 수 있는 주방과 비슷합니다.
↓
Node.js 실행 환경
↓
내 컴퓨터에서 JavaScript 실행
특히 Next.js, React 기반 프로젝트나 다양한 웹 개발 도구를 사용할 때 Node.js가 기본 개발 환경으로 사용되는 경우가 많습니다.
그래서 바이브코딩 도구로 새로운 웹 프로젝트를 만들다 보면 AI가 다음과 같이 안내하는 상황을 자주 만나게 됩니다.
이 말은 어려운 뜻이 아닙니다. 현재 컴퓨터에 JavaScript 기반 개발 프로젝트를 실행할 환경이 준비되어 있는지 확인하라는 의미입니다.
3. npm이란?
Node.js를 설치하면 함께 자주 사용하게 되는 것이 npm입니다. npm은 Node Package Manager의 약자로 알려져 있으며, 프로젝트에서 사용하는 각종 패키지를 관리하는 역할을 합니다.
웹서비스를 만들 때 모든 기능을 처음부터 직접 개발할 필요는 없습니다. 이미 다른 개발자들이 만들어 공개한 수많은 기능과 라이브러리를 활용할 수 있습니다.
예를 들어 날짜를 편리하게 처리하는 기능, 서버와 데이터를 주고받는 기능, 아이콘을 표시하는 기능 등은 이미 사용할 수 있는 패키지가 존재합니다.
이런 패키지를 프로젝트에 가져오는 대표적인 방법이 npm입니다.
예를 들어 다음 명령어를 실행했다고 해보겠습니다.
npm install axios여기서 axios는 서버와 HTTP 통신을 할 때 사용할 수 있는 패키지입니다. npm은 해당 패키지와 필요한 관련 파일들을 프로젝트에 설치해줍니다.
스마트폰에 필요한 기능이 있으면 앱스토어에서 앱을 설치하듯이, 개발 프로젝트에 필요한 기능이 있으면 npm을 이용해 패키지를 설치한다고 생각하면 이해하기 쉽습니다.
4. npm install은 무엇을 하는 명령어일까?
바이브코딩을 하면서 가장 많이 보게 될 npm 명령어 중 하나가 바로 npm install입니다.
프로젝트 파일을 다운로드하거나 GitHub에서 코드를 받아왔는데 바로 실행되지 않는 경우가 있습니다.
그 이유는 프로젝트 코드만 있고, 프로젝트에서 사용하는 외부 패키지가 아직 내 컴퓨터에 설치되어 있지 않기 때문일 수 있습니다.
이때 프로젝트 폴더의 터미널에서 다음 명령어를 실행합니다.
npm install그러면 npm이 프로젝트 설정을 확인한 뒤 필요한 패키지를 자동으로 설치합니다.
↓
package.json 확인
↓
npm install
↓
필요한 패키지 설치
↓
프로젝트 실행 준비 완료
그래서 GitHub에서 프로젝트를 내려받은 후 AI가 “먼저 npm install을 실행해주세요”라고 말한다면, 이 프로젝트가 사용하는 준비물을 설치하라는 의미라고 이해하면 됩니다.
5. package.json은 무엇일까?
npm을 사용하다 보면 거의 반드시 package.json이라는 파일을 만나게 됩니다.
package.json은 쉽게 말하면 현재 프로젝트의 설명서이자 준비물 목록입니다.
프로젝트 이름은 무엇인지, 어떤 패키지가 필요한지, 어떤 명령어로 프로젝트를 실행해야 하는지 등의 정보가 들어갈 수 있습니다.
예를 들어 package.json 안에는 다음과 비슷한 내용이 존재합니다.
{
"name": "my-project",
"scripts": {
"dev": "next dev",
"build": "next build"
},
"dependencies": {
"next": "...",
"react": "..."
}
}처음에는 이런 내용을 전부 이해할 필요는 없습니다.
| 항목 | 쉽게 이해하면 |
|---|---|
| name | 프로젝트 이름 |
| scripts | 프로젝트에서 사용할 수 있는 명령어 |
| dependencies | 프로젝트 실행에 필요한 패키지 목록 |
| devDependencies | 주로 개발 과정에서 사용하는 패키지 목록 |
package.json을 처음부터 직접 작성하려고 하지 않아도 됩니다.
바이브코딩에서는 대부분 프로젝트 생성 과정이나 npm 명령을 통해 자동으로 만들어지고 수정됩니다.
중요한 것은 “이 프로젝트가 어떤 패키지와 명령어를 사용하는지 확인할 수 있는 파일”이라는 점입니다.
6. npm run dev는 무슨 뜻일까?
바이브코딩으로 웹 프로젝트를 만들었다면 아마 매우 자주 보게 될 명령어가 있습니다.
npm run dev이 명령어는 보통 개발 중인 프로젝트를 실행할 때 사용합니다.
npm이 package.json의 scripts 영역을 확인하고, 그 안에 정의되어 있는 dev 명령을 실행합니다.
예를 들어 package.json에 다음과 같은 설정이 있다면,
"scripts": {
"dev": "next dev"
}터미널에서 npm run dev를 입력하면 실제로는 next dev 명령이 실행됩니다.
정상적으로 실행되면 터미널에서 다음과 비슷한 주소를 볼 수 있습니다.
http://localhost:3000브라우저에서 이 주소를 열면 내 컴퓨터에서 실행 중인 웹사이트를 확인할 수 있습니다.
“패키지 설치가 완료됐습니다. 터미널에서 npm run dev를 실행한 뒤 localhost:3000에서 확인해주세요.”
이제 이 문장의 의미를 알 수 있습니다.
필요한 패키지를 설치했으니 개발 서버를 실행하고, 브라우저에서 결과를 확인하라는 뜻입니다.
7. npm install과 npm run dev의 차이
초보자가 가장 많이 헷갈리는 것이 npm install과 npm run dev입니다.
| 명령어 | 역할 | 언제 사용? |
|---|---|---|
| npm install | 필요한 패키지 설치 | 프로젝트를 처음 받았거나 패키지를 설치해야 할 때 |
| npm run dev | 개발용 서버 실행 | 프로젝트를 브라우저에서 확인할 때 |
아주 간단하게 정리하면 다음과 같습니다.
= 준비물 설치
↓
npm run dev
= 프로젝트 실행
처음 프로젝트를 실행하는 상황이라면 보통 다음 순서가 됩니다.
npm install
npm run dev첫 번째 명령으로 필요한 패키지를 준비하고, 두 번째 명령으로 웹사이트를 실행합니다.
8. node_modules는 무엇일까?
npm install을 실행한 뒤 프로젝트 폴더를 보면 갑자기 node_modules라는 폴더가 생기는 것을 볼 수 있습니다.
node_modules는 npm으로 설치한 패키지들이 실제로 저장되는 공간입니다.
프로젝트에 따라 이 폴더에는 매우 많은 파일이 들어갈 수 있으며, 용량도 상당히 커질 수 있습니다.
node_modules 안의 파일을 초보자가 직접 수정할 필요는 거의 없습니다.
AI가 특별한 이유 없이 node_modules 내부 파일을 직접 수정하라고 한다면 왜 수정해야 하는지 먼저 확인하는 것이 좋습니다.
또한 Git을 사용할 때도 node_modules 전체를 GitHub에 올리지 않는 것이 일반적입니다. 필요한 패키지 목록은 package.json 등에 기록되어 있기 때문에 다른 컴퓨터에서는 다시 npm install을 실행해 설치할 수 있기 때문입니다.
9. npm에서 초보자가 자주 만나는 오류
npm 명령어는 간단해 보이지만, 개발 환경에 따라 오류가 발생할 수도 있습니다.
Node.js가 설치되지 않은 경우
터미널에서 npm 명령을 입력했는데 npm이라는 명령을 찾을 수 없다는 메시지가 나타날 수 있습니다.
이 경우 Node.js가 설치되지 않았거나, 설치는 되었지만 터미널에서 제대로 인식되지 않는 상황일 수 있습니다.
잘못된 폴더에서 실행한 경우
npm install이나 npm run dev는 보통 package.json 파일이 존재하는 프로젝트 폴더에서 실행해야 합니다.
엉뚱한 폴더에서 명령을 실행하면 package.json을 찾지 못했다는 오류가 나타날 수 있습니다.
패키지 버전이 충돌하는 경우
프로젝트에서 사용하는 여러 패키지의 버전이 서로 맞지 않으면 설치 과정에서 오류가 발생할 수도 있습니다.
오류가 발생했을 때 임의로 파일을 삭제하거나 설정을 바꾸기보다는 터미널에 표시된 오류 메시지와 현재 실행한 명령어를 AI에게 함께 전달하는 것이 좋습니다.
예:
“npm install을 실행했는데 아래 오류가 발생했어. 원인을 설명하고 초보자가 안전하게 해결할 순서를 알려줘.”
10. npm·Node.js·package.json 관계 한 번에 이해하기
지금까지 등장한 개념이 많아 보이지만 관계만 이해하면 생각보다 단순합니다.
| 용어 | 초보자식 설명 |
|---|---|
| Node.js | JavaScript 기반 프로젝트를 컴퓨터에서 실행할 수 있는 환경 |
| npm | 프로젝트에 필요한 패키지를 설치하고 관리하는 도구 |
| package.json | 프로젝트 정보와 필요한 패키지, 실행 명령이 적힌 설명서 |
| node_modules | npm으로 설치한 실제 패키지가 들어가는 폴더 |
| npm install | 필요한 패키지를 설치하는 명령 |
| npm run dev | 개발 중인 프로젝트를 실행하는 대표적인 명령 |
↓
프로젝트 열기
↓
package.json 확인
↓
npm install
↓
node_modules 생성
↓
npm run dev
↓
localhost에서 결과 확인
11. 바이브코딩 초보자는 어디까지 알면 될까?
npm이나 Node.js에는 훨씬 더 많은 기능과 개념이 있습니다. 하지만 바이브코딩 입문 단계에서 모든 내용을 공부할 필요는 없습니다.
우선 아래 정도만 이해하면 충분합니다.
✅ Node.js는 JavaScript 프로젝트를 실행할 수 있는 환경입니다.
✅ npm은 프로젝트에 필요한 패키지를 관리합니다.
✅ package.json에는 프로젝트의 패키지와 명령어 정보가 들어 있습니다.
✅ npm install은 필요한 패키지를 설치합니다.
✅ npm run dev는 개발 프로젝트를 실행할 때 자주 사용합니다.
✅ node_modules는 설치된 패키지가 저장되는 폴더입니다.
이 정도를 이해했다면 앞으로 Cursor나 Claude Code가 “npm install을 실행하세요”, “package.json의 scripts를 확인하세요”, “npm run dev로 개발 서버를 실행하세요”라고 말해도 무슨 작업을 하는지 이해할 수 있습니다.
바이브코딩에서 중요한 것은 모든 명령어를 외우는 것이 아닙니다. AI가 지금 어떤 작업을 하려고 하는지 이해하고, 그 작업이 정상적으로 진행됐는지 확인할 수 있는 정도의 지식을 갖추는 것입니다.
12. 정리
이번 글에서는 바이브코딩 과정에서 매우 자주 등장하는 npm, Node.js, package.json을 알아봤습니다.
처음에는 낯선 용어처럼 보이지만 실제 개발 흐름에 연결해보면 어렵지 않습니다.
실행 환경
↓
npm
패키지 관리
↓
package.json
프로젝트 설정
↓
npm install
패키지 설치
↓
npm run dev
프로젝트 실행
여기까지 이해했다면 이제 바이브코딩 프로젝트를 다운로드하고 필요한 패키지를 설치한 뒤 직접 실행하는 기본 흐름을 이해한 것입니다.
앞선 터미널과 Git/GitHub까지 함께 이해했다면 이제 실제 AI 코딩 도구를 사용하기 위한 기초 준비도 상당 부분 끝났습니다.
다음 편에서는 실제 바이브코딩에서 사용하는 Cursor, Claude Code, Codex 같은 AI 코딩 도구가 무엇이고 각각 어떤 방식으로 개발을 도와주는지 알아보겠습니다.