npm 패키지와 의존성을 장보기 목록처럼 읽는 법

바이브코딩을 하다 보면 AI가 ‘npm install’을 실행하라고 제안합니다. 짧은 명령이지만 프로젝트 밖에서 코드를 내려받고 파일을 바꿀 수 있습니다. 무엇이 들어오는지 모른 채 실행하면 예상하지 못한 버전 변화나 설치 스크립트까지 함께 받아들일 수 있습니다.

npm은 JavaScript 패키지를 찾고 설치하고 관리하는 도구입니다. 패키지는 다른 프로젝트에서도 쓸 수 있도록 코드와 설명 파일을 한 묶음으로 만든 것입니다. 장을 볼 때 재료를 직접 기르지 않고 필요한 상품을 사 오는 것처럼, 날짜 계산이나 화면 구성 같은 기능을 검토해 가져올 수 있습니다.

패키지는 재사용 가능한 코드 상자다

패키지에는 보통 실행 코드, 버전, 사용법, 라이선스 정보가 들어 있습니다. 프로젝트가 그 패키지에 기대어 작동하면 의존성이라고 부릅니다. 의존성은 어려운 별도 물건이 아니라 ‘내 코드가 필요로 하는 다른 코드’라는 관계입니다.

한 패키지가 또 다른 패키지를 필요로 할 수도 있습니다. 내가 직접 고른 재료뿐 아니라 완제품 안에 들어간 원재료까지 따라오는 모습과 같습니다. 그래서 설치 전에는 이름 하나만 볼 것이 아니라 그 패키지가 유지되고 있는지, 어떤 권한과 설치 동작이 있는지, 기존 코드와 맞는 버전인지 확인해야 합니다.

package.json은 필요한 물건을 적은 목록이다

package.json은 프로젝트 이름, 실행 명령, 필요한 패키지와 허용 버전 범위를 적는 설명 파일입니다. npm 공식 문서는 dependencies를 패키지 이름과 버전 범위를 연결한 객체로 설명합니다. ‘^’나 ‘~’ 같은 기호는 설치 가능한 버전 범위를 바꿀 수 있으므로 모르면 임의로 수정하지 않습니다.

‘dependencies’에는 서비스가 실제로 실행될 때 필요한 패키지를, ‘devDependencies’에는 테스트나 빌드처럼 개발할 때 주로 필요한 도구를 둡니다. 어느 칸에 있느냐가 보안 등급을 뜻하지는 않습니다. 두 종류 모두 공급망과 버전 변화를 살펴야 합니다.

{
  "dependencies": { "date-fns": "^3.6.0" },
  "devDependencies": { "vitest": "^3.2.4" }
}

이 예시는 날짜 기능은 실행 의존성, 테스트 도구는 개발 의존성으로 기록한 모습입니다. 버전을 보고 최신이라고 추측하지 말고 프로젝트의 현재 잠금 파일과 공식 변경 기록을 같이 봅니다.

package-lock.json은 실제 구매 영수증에 가깝다

package-lock.json은 npm이 실제로 만든 전체 의존성 트리와 정확한 버전을 기록합니다. npm 공식 문서에 따르면 이 파일은 이후 설치에서도 같은 트리를 만들 수 있게 돕고, 저장소에 함께 커밋하도록 의도됐습니다. 장보기 목록이 ‘우유 한 통’이라면 잠금 파일은 어느 제품의 어느 규격을 샀는지 적힌 영수증에 가깝습니다.

잠금 파일은 매우 길 수 있지만 손으로 일부만 고치면 package.json과 어긋날 수 있습니다. 충돌이 났다는 이유로 통째로 삭제하고 다시 설치하면 많은 하위 버전이 한꺼번에 달라질 수 있습니다. 변경 원인을 모르면 먼저 Git diff로 어느 명령이 어떤 줄을 바꿨는지 확인합니다.

설치 명령마다 바뀌는 범위가 다르다

‘npm install’은 현재 목록을 바탕으로 패키지를 설치하고 조건에 따라 package-lock.json을 갱신합니다. 패키지 이름을 뒤에 붙이면 package.json도 바뀔 수 있습니다. ‘npm ci’는 자동화 환경에서 잠금 파일을 기준으로 깨끗하게 설치할 때 자주 쓰이지만, 기존 설치 폴더를 다루므로 개인 작업 폴더에서 의미를 모르고 실행할 명령은 아닙니다.

설치 후에는 파일이 생겼다는 사실과 앱이 정상이라는 사실을 나눠 확인합니다. 빌드, 테스트, 브라우저 화면을 각각 통과해야 기존 기능과의 충돌을 찾을 수 있습니다. 오류가 나면 무작정 다른 버전을 반복 설치하지 말고 첫 오류와 변경 파일을 기록합니다.

안전한 패키지 추가는 확인부터 시작한다

• 공식 패키지 페이지에서 정확한 이름과 저장소 주소를 확인합니다.
• 현재 package.json과 package-lock.json을 Git으로 저장해 복구 지점을 만듭니다.
• 설치 명령이 추가, 삭제, 업데이트 중 무엇을 하는지 설명할 수 있는지 봅니다.
• 설치 뒤 Git diff에서 두 설명 파일과 예상한 코드만 바뀌었는지 확인합니다.
• 테스트와 빌드를 실행하고 실제 화면의 기존 기능도 확인합니다.
• 필요 없어진 패키지는 코드 사용처를 찾은 뒤 공식 제거 명령을 검토합니다.

이 과정은 택배 상자를 받기 전에 주문 내역과 발신자를 대조하는 일과 비슷합니다. 다운로드 수만 많다고 안전하거나 내 프로젝트와 맞는 것은 아닙니다. 라이선스, 유지보수 상태, 보안 공지도 실제 채택 전에 확인해야 합니다.

오늘 바로 해볼 작은 실습

새 패키지를 설치하지 말고 현재 프로젝트의 설명 파일만 읽어 봅니다.

1. 파일 탐색기에서 package.json을 엽니다.
2. dependencies와 devDependencies에서 이름을 하나씩 고릅니다.
3. 각 패키지가 실행 기능인지 개발 도구인지 한 문장으로 추측합니다.
4. package-lock.json에서 같은 이름을 검색해 실제 기록된 버전을 봅니다.
5. package.json의 허용 범위와 잠금 파일의 버전이 왜 다른 표현인지 적습니다.
6. 변경 사항이 없는지 Git 상태를 읽기 전용으로 확인합니다.

모르는 설치 명령, ‘sudo’가 붙은 명령, 출처를 확인하지 못한 패키지는 실행하지 마세요. 비밀키를 명령줄 인자나 패키지 설정 예시에 넣지 않고, 실제 서비스 결제와 배포 프로젝트에서는 담당자 승인 없이 의존성을 바꾸지 않습니다. package.json은 계획이고 package-lock.json은 재현 기록이라는 차이를 기억하면 AI의 설치 제안을 훨씬 안전하게 검토할 수 있습니다.