npm 주요 명령어 정리

Node.js 초심자들이 npm 패키지를 설치할 때 헷갈려 할만한 경우가 많다. 과거 작성된 문서에서는 패키지 설치 명령어로 npm install --save <패키지명>을 사용하는 경우가 많았고, 지금도 npm install <패키지명>, npm install -D <패키지명>, npm i <패키지명> 등이 혼재되어 있어 이를 명확히 이해하지 못하면 혼란할 수 있다. 이에 npm 패키지 관리 명령어를 정리해본다.

버전 확인

• npm -v: npm(패키지 매니저) 버전 확인
• node -v: Node.js(노드 런타임) 버전 확인

프로젝트 초기화

• npm init: 노드 프로젝트 초기화. 패키지 및 의존성 관리를 위한 package.json 파일 생성됨.
  • npm init -y: npm init 실행 시 대화식(interactive)으로 설정할 수 있는데, 모두 기본값 혹은 yes로 설정

프로젝트 설정

• npm config list: 현재 npm의 모든 설정 목록 확인
• npm set <key> <value>: 특정 설정 값 변경
• npm get <key>: 특정 설정 값 확인

목록 확인

• npm ls: 설치된 패키지와 의존성 트리 출력
  • npm ls --depth=0: 최상위 패키지만 나열

install(설치)

• npm install <패키지명>: 현재 노드 프로젝트에 패키지 설치 및 의존성 추가
  • npm install --save <패키지명>와 동일(기본값)
  • npm i <패키지명>로도 사용 가능
  • package.json 파일의 'dependencies'에 의존성이 추가됨
• npm install -D <패키지명>: 현재 노드 프로젝트에서 패키지 및 의존성을 개발용으로 추가
  • npm i -D <패키지명>로도 사용 가능
  • package.json 파일의 'devDependencies'에 의존성이 추가됨
  • devDependencies는 개발 환경에서만 추가되고 테스트, 운영 환경에서는 추가되지 않음

uninstall(삭제)

• npm uninstall <패키지명>: 설치된 패키지 및 의존성 제거
  • npm un <패키지명>으로도 사용 가능
  • node_modules에서 해당 패키지 삭제
  • package.json 파일에서 해당 의존성 삭제

전역 패키지

• npm install -g <패키지명>: 사용자의 노드 환경에 패키지 전역 설치
• npm uninstall -g <패키지명>: 전역 설치 패키지 삭제
• npm list -g --depth=0: 전역 설치 패키지 목록 확인
• npm update -g ( <패키지명>): (모든) 전역 패키지 최신 버전으로 업데이트

업데이트

• npm outdated: 업데이트가 필요한 패키지 목록 확인
• npm update <패키지명>: 특정 패키지를 최신(latest) 버전으로 업데이트

스크립트

• npm run <script명>: package.json에 정의된 스크립트 실행
  • npm start: start 스크립트 실행
    • npm run start의 단축 명령어(동일)
  • npm test: test 스크립트 실행
    • npm run test의 단축 명령어(동일)
  • npm stop: stop 스크립트 실행
    • npm run stop의 단축 명령어(동일)
  • npm restart: restart 스크립트 실행
    • npm run restart의 단축 명령어(동일)

기타

• npm cache clean --force: npm 캐시 강제 삭제
• npm ci: package-lock.json 기반 의존성 재설치
  • 기존 node_modules를 삭제하고 재설치
• npm doctor: 환경 상태 점검 및 문제 확인
• npm audit: 보안 취약점 분석
  • npm audit fix: 보안 문제 자동 수정

npm access: 패키지 접근 권한 관리 (읽기/쓰기 권한 설정 등)
npm adduser: npm 사용자 계정을 추가하거나 로그인
npm bugs: 패키지의 버그 추적 URL 열기
npm completion: 쉘 자동완성 스크립트를 출력
npm dedupe: 중복된 의존성을 제거하여 node_modules를 최적화
npm deprecate: 특정 버전을 더 이상 사용하지 않도록 표시
npm dist-tag: 배포 태그 관리 (예: 최신 버전 태그 설정)
npm edit: 로컬에 설치된 패키지 파일을 편집
npm explain: 특정 패키지 의존성의 원인을 설명
npm explore: 설치된 패키지의 폴더로 이동
npm hook: 패키지 배포 시 발생하는 웹훅 관리
npm install-test: 패키지 설치 후 정의된 테스트 스크립트를 실행
npm org: npm 조직 관리 (사용자 그룹 생성 및 관리)
npm owner: 패키지 소유권 관리 (소유자 추가/제거)
npm ping: npm 레지스트리에 연결 상태 확인
npm prefix: 현재 프로젝트의 루트 디렉토리 경로 출력
npm profile: npm 사용자 프로필 설정 및 업데이트
npm repo: 패키지의 Git 저장소 URL 열기
npm search: npm 레지스트리에서 패키지 검색
npm star: 특정 패키지에 별(star)을 누르기
npm stars: 사용자가 별(star)을 누른 패키지 목록 표시
npm team: npm 조직의 팀 구성원 관리
npm token: 배포용 인증 토큰 생성 및 관리 (생성, 조회, 삭제 가능)

설치 없이 패키지 실행

• npx <패키지명>: 패키지를 전역 설치 없이 실행 (로컬 패키지, 원격 패키지 모두 실행 가능)

정리

가장 중요하고 가장 많이 사용하는 명령어

1. npm install <패키지명> 또는 npm i <패키지명>
   기본적으로 패키지를 프로젝트의 dependencies에 추가한다. 이는 런타임 환경에서 필요한 패키지를 설치할 때 주로 사용한다.
2. npm install -D <패키지명> 또는 npm i -D <패키지명>
   개발 환경에서만 필요한 패키지를 설치할 때 사용하며, devDependencies에 추가된다. 운영 환경에서는 이 패키지들이 포함되지 않는다.

전역 패키지 사용 지양하기

Node.js 프로젝트를 혼자 개발할 때는 전역 패키지를 사용하는 것이 큰 문제가 되지 않을 수 있다. 그러나 협업 환경에서는 전역 패키지를 사용하는 것이 여러 문제를 야기한다.

예를 들어:

• 원 개발자가 전역 패키지를 사용하면 협업 개발자가 npm install을 실행해도 해당 패키지가 설치되지 않는다.
• 의존성이 추가되지 않은 상태에서는 프로젝트가 실행되지 않으며, 버전 불일치 문제도 발생할 수 있다.
• 원 개발자가 최신 버전으로 작업했더라도, 협업자가 클론한 시점에서는 해당 버전이 더 이상 최신이 아닐 수 있다.

특히 원 개발자가 팀에 없다면, 어떤 버전을 사용해야 하는지 확인하기 어려워져 문제를 해결하기 매우 힘들어진다.

결론

전역 설치는 CLI 도구에 한정하고, 프로젝트 환경에 필요한 패키지는 반드시 로컬에 설치한다. 필자 역시 이런 원칙을 지키며, 모든 프로젝트에서 npm install <패키지명> 또는 npm install -D <패키지명>을 사용해 의존성을 관리한다.