npm install 할 때마다 궁금했던 것
Node.js도 설치했고, 터미널에서 npm install도 실행했습니다. 뭔가 엄청 많이 출력됐고 끝났습니다.
"잘 된 건가? 뭘 설치한 건가? 이 파일들은 어디 갔나? 갑자기 폴더가 엄청 무거워졌는데 괜찮은 건가?"
AI가 이번엔 "npm install recharts를 실행하세요"라고 했습니다. 또 실행했습니다. 또 뭔가 출력됐습니다.
"recharts가 뭔지도 모르는데 설치가 된 건가? 다음에 또 다른 걸 설치하면 어떻게 되나?"
이전 글들에서 npm이 "기능을 설치하는 앱스토어"라는 개념을 잡았고, 터미널에서 npm install을 실제로 실행해봤습니다. 이번에는 그 명령어를 실행하면 내부에서 실제로 무슨 일이 일어나는지를 들여다봅니다.
요즘 개발은 모든 기능을 처음부터 직접 만드는 방식이 아닙니다. 로그인, 차트, 날짜 처리, 애니메이션 같은 기능은 이미 전 세계 개발자들이 만들어 공개해둔 패키지를 가져다가 조합하는 방식에 가깝습니다. AI 역시 이런 패키지들을 활용해 앱을 빠르게 구성합니다. npm install은 그 "공개된 기능 상자를 인터넷에서 내려받아 내 프로젝트 안에 넣는 것"입니다. 직접 만들 필요가 없는 것을 직접 만들지 않는 것이 현대 개발의 핵심입니다.
npm install을 하면 실제로 일어나는 일
npm install을 실행하는 순간 세 가지 일이 순서대로 일어납니다.
① package.json을 읽는다
npm이 가장 먼저 프로젝트 루트에 있는 package.json 파일을 열어봅니다. "이 프로젝트에 어떤 패키지가 필요한지" 목록이 여기에 적혀 있습니다.
② npmjs.com에서 패키지를 내려받는다
목록에 있는 패키지들을 인터넷에서 다운로드합니다. 이때 각 패키지가 의존하는 다른 패키지들도 함께 받아옵니다. 그래서 하나를 설치해도 수십~수백 개가 다운로드됩니다.
💡 처음 설치할 때는 수십 초~몇 분 걸릴 수 있습니다. 영어 로그가 계속 지나가도 대부분 정상입니다. 마지막 줄에 빨간 error가 없으면 성공입니다.
③ node_modules 폴더에 저장한다
내려받은 파일들을 프로젝트 안의 node_modules 폴더에 저장합니다. 이 폴더가 npm install 후 갑자기 커지는 이유입니다.
package.json — 이 프로젝트의 재료 목록
package.json은 프로젝트 루트에 있는 파일로, 이 프로젝트가 어떤 패키지를 쓰는지 기록한 목록입니다. 요리로 비유하면 레시피 재료 목록에 해당합니다.
버전 번호 앞의 ^ 기호는 뭔가요?
버전 번호 앞에 ^(캐럿) 기호가 붙어 있는 경우가 많습니다. "이 버전 이상의 호환되는 버전이면 OK"라는 뜻입니다. 지금 단계에서 이 기호의 의미를 깊이 알 필요는 없습니다. 직접 수정하지 않는 것이 안전합니다. AI가 자동으로 관리해줍니다.
새 패키지를 npm install로 설치하면 package.json에 자동으로 추가됩니다. 삭제하면 자동으로 빠집니다. 직접 손대지 않아도 AI가 패키지를 추가·제거할 때 자동으로 관리합니다. 이 파일이 있으면 어떤 컴퓨터에서든 npm install 한 번으로 같은 환경을 복원할 수 있습니다.
node_modules — 왜 이렇게 크고 GitHub에 올리면 안 되나
npm install을 실행하고 나면 프로젝트 폴더 안에 node_modules라는 폴더가 생깁니다. 열어보면 수백 개의 폴더가 있고, 용량이 100MB~수백 MB에 달하는 경우도 있습니다. 왜 이렇게 클까요?
node_modules가 수백 개인 이유가 있습니다. recharts 하나를 설치했는데 recharts가 내부적으로 의존하는 다른 패키지들이 줄줄이 딸려옵니다. 그것들이 또 다른 패키지에 의존하고… 이 연쇄가 반복되면서 수백 개가 됩니다. 이것을 의존성(dependency)이라고 합니다.
✅ node_modules는 필요하면 언제든 다시 다운로드할 수 있습니다. 폴더가 커서 불안하다면 삭제해도 됩니다. package.json만 있으면 npm install 한 번으로 완전히 복원됩니다. 그래서 GitHub에도 올리지 않습니다.
왜 GitHub에 올리지 않나요?
수백 MB를 매번 GitHub에 올리고 받으면 저장소가 무거워지고 속도가 느려집니다.
package.json만 있으면 어디서든 npm install 한 번으로 node_modules를 다시 만들 수 있습니다.
AI가 프로젝트를 생성할 때 .gitignore 파일에 node_modules/가 자동으로 포함됩니다. 별도로 설정하지 않아도 GitHub에 올릴 때 node_modules는 자동으로 제외됩니다. 다른 컴퓨터에서 프로젝트를 clone한 후 npm install을 실행하면 node_modules가 다시 만들어집니다.
바이브 코딩에서 자주 만나는 패키지 카테고리
AI가 npm install을 시킬 때 어떤 종류의 패키지를 설치하는 건지 알면, 낯선 이름이 나와도 "아, 이런 역할이구나"로 분류할 수 있습니다. 외울 필요는 없습니다. 이름만 봐도 카테고리가 떠오를 정도면 충분합니다.
UI · 스타일링
tailwindcss, shadcn/ui화면 디자인과 레이아웃을 담당합니다. AI가 보기 좋은 UI를 만들 때 주로 씁니다.
차트 · 시각화
recharts, chart.js데이터를 그래프로 보여줄 때 씁니다. 대시보드나 통계 화면에 자주 등장합니다.
데이터베이스 연결
@supabase/supabase-jsSupabase 같은 외부 DB와 연결할 때 씁니다. 데이터 저장이 필요한 모든 앱에서 등장합니다.
날짜 · 시간 처리
date-fns, dayjs날짜 계산, 포맷 변환 등에 씁니다. "3일 전", "2026년 5월 13일" 같은 표시에 필요합니다.
폼 · 입력 처리
react-hook-form, zod로그인 폼, 입력 유효성 검사에 씁니다. "이메일 형식이 맞는지 확인"도 여기서 처리됩니다.
AI · API 연결
openai, @anthropic-ai/sdkOpenAI, Anthropic 같은 AI API를 앱에 연결할 때 씁니다. AI 기능을 추가하는 핵심 패키지입니다.
AI가 처음 보는 패키지를 설치하라고 하면 npmjs.com에서 이름을 검색해보세요. 다운로드 수, 마지막 업데이트 날짜, 설명이 나옵니다. 주간 다운로드가 수백만 이상이고 최근에 업데이트됐다면 믿을 만한 패키지입니다.
npm vs npx — AI가 두 가지를 섞어 쓰는 이유
바이브 코딩을 하다 보면 AI가 두 가지 형태의 명령어를 번갈아 씁니다. npm install로 시작하는 것과 npx로 시작하는 것. 둘이 다릅니다.
설치하고 두고두고 쓰는 것
패키지를 node_modules에 저장합니다. 한 번 설치하면 계속 쓸 수 있습니다.
설치 없이 즉시 실행하는 것
패키지를 저장하지 않고 바로 실행합니다. 새 프로젝트 생성 같은 일회성 작업에 씁니다.
정리하면 이렇습니다. 앱 기능으로 계속 쓸 패키지는 npm install로 설치하고, 새 프로젝트를 만들거나 설정 도구를 한 번만 쓸 때는 npx를 씁니다. 어떤 것을 써야 하는지는 AI가 알아서 골라서 알려줍니다. 그대로 복붙하면 됩니다.
설치했는데 작동 안 할 때 — 상황별 대처법
npm install을 했는데 앱이 오류가 나거나 패키지가 인식되지 않는 경우가 있습니다. 아래 세 가지가 가장 흔한 원인과 해결법입니다.
🔧 상황 1 — node_modules가 꼬인 경우
여러 번 패키지를 설치·삭제하다 보면 node_modules 안에 충돌이 생길 수 있습니다. 가장 쉬운 해결법은 node_modules를 완전히 지우고 다시 설치하는 것입니다.
🔧 상황 2 — 패키지를 설치했는데 "Cannot find module" 오류
설치는 됐는데 코드에서 인식을 못 하는 경우입니다. 대부분 세 가지 원인입니다.
🔧 상황 3 — 패키지 버전 충돌 (peer dependency warning)
터미널에 노란색 경고로 peer dependency 관련 메시지가 나오는 경우입니다. 바로 해결이 어려운 경우가 많지만 대부분 앱 실행에는 영향이 없습니다.
이전 글 → [[터미널 비개발자 최소 생존 가이드 — 바이브 코딩에서 실제로 쓰는 명령어 5가지]] 다음 글(차후 업로드 예정) → [[VS Code 폴더 구조 읽는 법 — 파일이 수십 개인 이유와 어디를 봐야 하는지]]
📌 핵심 정리
- npm install은 "이미 만들어진 기능 상자를 인터넷에서 내려받아 내 프로젝트에 넣는 것"입니다. 요즘 개발은 모든 기능을 직접 만들지 않고, 전 세계 개발자들이 공개해둔 패키지를 조합합니다. AI도 이 방식으로 앱을 구성합니다.
- npm install은 package.json을 읽어 필요한 패키지를 npmjs.com에서 내려받아 node_modules에 저장합니다. 수백 개가 설치되는 것은 의존성 패키지들이 함께 오기 때문으로 정상입니다. 영어 로그가 계속 흘러도 마지막에 error가 없으면 성공입니다.
- package.json은 이 프로젝트의 재료 목록입니다. 직접 수정하지 않아도 패키지 설치·삭제 시 자동으로 업데이트됩니다. 이 파일 하나만 있으면 어디서든 npm install로 환경을 복원할 수 있습니다.
- node_modules는 필요하면 언제든 다시 다운로드할 수 있습니다. 폴더가 커서 불안해도 삭제하면 됩니다. package.json만 있으면 npm install 한 번으로 완전히 복원됩니다. 그래서 GitHub에 올리지 않습니다.
- npm은 패키지를 설치해 node_modules에 보관하는 것이고, npx는 설치 없이 즉시 실행하는 것입니다. AI가 어떤 것을 쓸지 알려주므로 그대로 복붙하면 됩니다.
- 패키지가 작동하지 않을 때 가장 먼저 시도할 것은 node_modules를 삭제하고 npm install을 다시 실행하는 것입니다. 그래도 안 되면 에러 메시지를 AI에게 복붙하세요.
❓ 자주 묻는 질문
node_modules 폴더는 왜 이렇게 크고, GitHub에 올리면 안 되나요?
node_modules는 npm install로 설치된 패키지 파일들이 실제로 저장되는 폴더입니다. 수백 개의 패키지가 담기기 때문에 수백 MB에 달하는 경우도 있습니다. GitHub에 올리지 않는 이유는 두 가지입니다. 첫째, 용량이 너무 커서 저장소가 무거워집니다. 둘째, package.json만 있으면 npm install 한 번으로 언제든 다시 생성할 수 있기 때문입니다. .gitignore에 node_modules/가 자동으로 포함되어 있어서 따로 설정하지 않아도 됩니다.
package.json이 뭔가요? 직접 수정해도 되나요?
package.json은 이 프로젝트가 어떤 패키지를 사용하는지 기록한 목록 파일입니다. 새 패키지를 설치하면 자동으로 여기에 추가됩니다. 직접 수정하는 것은 가능하지만, 바이브 코딩 입문 단계에서는 AI가 수정해주도록 요청하는 것이 안전합니다. 버전 번호를 잘못 수정하면 패키지 충돌이 생길 수 있습니다.
npm과 npx의 차이가 뭔가요?
npm install은 패키지를 내 컴퓨터에 설치해 보관하는 명령어이고, npx는 설치 없이 패키지를 즉시 실행하는 명령어입니다. AI가 'npx create-next-app'처럼 npx로 시작하는 명령어를 알려줄 때가 있는데, 이때는 패키지를 설치하지 않고 바로 실행합니다. 새 프로젝트를 만들거나 일회성 도구를 실행할 때 주로 npx를 씁니다. 어떤 것을 써야 할지는 AI가 알려주므로 그대로 복붙하면 됩니다.
npm install 후 패키지가 작동하지 않을 때 어떻게 하나요?
가장 먼저 터미널 에러 메시지를 복사해 AI에게 붙여넣으세요. 자주 발생하는 원인은 세 가지입니다. 첫째, node_modules 폴더가 꼬인 경우 — node_modules 폴더를 삭제하고 npm install을 다시 실행합니다. 둘째, npm run dev를 재시작하지 않은 경우 — Ctrl+C로 종료 후 npm run dev를 다시 실행합니다. 셋째, 패키지 이름을 잘못 입력한 경우 — npmjs.com에서 정확한 이름을 확인합니다.
이제 package.json을 열어보세요
VS Code 왼쪽 파일 목록에서 package.json을 클릭해 열어보세요.
지금까지 설치한 패키지들이 목록으로 적혀 있습니다.
"아, 이게 재료 목록이구나"가 느껴지면 됩니다.
댓글 쓰기