자바스크립트 패키지 설치법 완벽 가이드 (npm install)

npm 저장소는 모든 프로그래밍 언어를 통털어 명실상부 가장 큰 패키지 저장소입니다. 자바스크립트 개발자들은 편리하게 npm install 명령어를 사용하여 npm 저장소로부터 다양한 패키지를 내려받아 사용하고 있는데요.

이번 포스팅에서는 워낙 자주 사용하다 보니 의외로 잘 모를 수 있는 npm install 명령어를 사용하는 방법에 대해서 알아보려고 합니다.

별도 포스팅에서 자바스크립트 개발자를 위한 필수 npm 커맨드도 정리해두었으니 참고바랍니다.

npm install의 별칭

npm install 명령어는 여러가지 별칭이 있는데요. 대표적으로 npm i와 npm add를 들 수 있습니다.

예를 들어, 유효성 검증 라이브러리리인 Zod를 설치할 때 다음 명령어 중 어떤 것을 사용해도 무방합니다.

$ npm install zod

$ npm i zod

$ npm add zod

저는 개인적으로 워낙 자주 쓰는 명령어라 타이핑을 제일 적게할 수 있는 npm i를 선호하는데요. 자칫 npm init 명령어와 헛갈릴 수도 있기 때문에 npm install을 쓰기도 합니다.

package.json 변경 여부 설정

아주 예전에 npm install 명령어를 실행할 때 무조건 -S 또는 --save를 붙이라고 하던 시절이 있었습니다. npm 초창기 버전에서는 이 옵션없이 npm install 명령어를 실행하면, 패키지를 node_modules 폴더 안에 다운로드만 해놓고 package.json 파일은 건들지 않았기 때문인데요.

이제는 굳이 -S 또는 --save를 붙이지 않더라도 패키지의 이름과 버전이 package.json 파일의 dependencies 영역에 자동으로 추가됩니다. 하지만 아직도 오래된 문서를 보면, 이 옵션을 사용하라고 가이드되어 있는 것을 종종 보실 수 있으실 거에요.

예를 들어, 다음과 같이 -S 또는 --save를 붙이든,

$ npm i -S zod

$ npm install --save zod

다음과 같이 아무 옵션을 사용하지 않든,

$ npm i zod

$ npm install zod

프로젝트의 package.json 파일을 열어보시면 아래와 같이 똑같이 패키지 이름과 버전이 추가된 것을 보실 수 있으실 거에요.

{
  "dependencies": {
    "zod": "^3.22.4"
  }
}

오히려 반대로 옛날처럼 package.json 파일을 변경하지 않고 패키지만 내려받고 싶으면 요즘에는 --no-save라는 옵션을 써야합니다.

$ npm i --no-save zod

하지만 일회성으로 패키지를 사용하는 게 아니라면 그럴 일은 거의 없겠죠? 항상 내려받은 패키지를 package.json 파일에 반영하여 같은 프로젝트에서 협업하는 다른 개발자에게 문제가 생기지 않도록 해야겠습니다.

package.json 파일에 대해서는 별도 포스팅에서 자세히 다루고 있으니 참고 바랍니다.

개발 의존성으로 설치

애플리케이션 실행 시점에는 필요하지 않지만 개발하는 동안에는 필요한 패키지는 개발 의존성으로 설치를 해야하는데요. 개발 의존성으로 패키즤를 설치할 때는 -D 또는 --save-dev 옵션을 사용합니다.

예를 들어, 자바스크립트에서 가장 많이 사용되는 ESLint를 개발 의존성으로 설치하려면 아래와 같이 실행합니다.

$ npm i -D eslint

$ npm install --save-dev eslint

개발 의존성으로 설치된 패키지의 이름과 버전은 package.json 파일의 devDependencies 영역에 자동으로 추가됩니다.

전역에 설치

간혹 패키지를 현재 디렉터리 뿐만 아니라 컴퓨터의 어느 경로에서나 실행할 수 있도록 전역으로 설치해야 할 때가 있습니다. 이렇게 특정 프로젝트에 국한되지 않는 패키지를 설치할 때는 -g 또는 --global 옵션을 사용합니다.

예를 들어, 타입스크립트를 전역으로 설치하려면 아래와 같이 실행합니다.

$ npm i -g typescript

$ npm install --global typescript

이렇게 전역으로 설치된 패키지하면 node_modules 디렉토리나 package.json 파일에는 아무 변화가 일어나지 않습니다. 대신에 전역 패키지들은 Node.js가 설치된 경로 아래에 lib/node_modules에 내려받아지는데요. 터미널에 npm root -g라고 입력하면 정확한 경로를 확인하실 수 있으실 거에요.

설치된 패키지의 버전 고정

npm install 명령어로 패키지를 설치하면 기본적으로는 버전 앞에 ^ 기호가 붙어서 package.json 파일에 추가가 되는데요. 이렇게 버전을 영역으로 지정해주면 npm이 프로젝트의 의존성 트리를 관리할 때 최적화가 용이해지며, 나중에 해당 패키지의 새로운 패치(patch)나 마이너(minor) 버전이 출시되었을 때 npm update 명령어를 통해 안전한 업그레이드도 가능해집니다.

하지만 영역으로 버전을 지정하면 공급망 공격(Supply-chain Attack)에 취약해지기 때문에 보안에 민감한 프로젝트의 경우 영역으로 버전을 지정하는 것을 금지하는 경우도 있습니다. 이럴 때는 -E 또는 --save-exact 옵션을 사용하여 패키지의 버전을 npm에 등록된 최신 버전으로 고정(pin)시킬 수 있습니다.

$ npm i -E zod

$ npm install --save-exact zod

{
  "dependencies": {
    "zod": "3.22.4"
  }
}

package.json에 나열된 모든 패키지 설치

npm install 명령어는 프로젝트에 새로운 패키지를 추가할 때 뿐만 아니라, package.json에 나열된 모든 패키지를 일괄 설치를 할 때도 많이 쓰는데요. Git 저장소에서 프로젝트를 처음 클론(clone) 받으셨거나, node_modules 폴더가 지워졌을 때 유용하게 사용할 수 있습니다.

새로운 패키지를 추가할 때는 npm install <패키지>@<버전> 형태를 쓰잖아요? 여기서 <패키지>@<버전>를 명시하지 않고 그냥 npm install 명령어만 실행해주시면 됩니다.

$ npm i

$ npm install

CI, 운영 환경에서 패키지 설치

개발자 PC가 아닌 CI나 QA, 운영 환경의 서버에 패키지를 설치할 때는 좀 더 주의할 부분이 생기는데요.

예를 들어, 패키지 잠금을 해주는 package-lock.json이 없거나, package.json과 맞지 않는 부분이 있다면 보안 문제를 초래할 수 있기 때문에 패키지 설치를 중단해야합니다. 그리고 배포 환경에 node_modules 폴더가 이미 있더라도 재사용하기 보다는 삭제하고 매번 새로 설치하는 것이 안전합니다. 또한, 운영 환경에서는 개발 도구가 사용되지 않기 때문에 굳이 개발 의존성인 패키지를 설치할 필요가 없죠.

이를 위해 npm에서는 아예 별도의 최적화된 설치 명령어를 제공하고 있습니다.

$ npm ci

$ npm clean-install

따라서 CI 서버나 운영 환경에서는 위 명령어를 사용하여 패키지를 설치하는 것이 권장되겠습니다.

npm ci 명령어는 NODE_ENV 환경 변수의 값이 production으로 설정되어 있으면 개발 의존성 패키지 설치는 생략합니다. 만약에 어떤 이유로든 개발 의존성의 패키지도 설치를 원한다면 --included=dev 옵션을 붙여주시면 됩니다.

$ npm ci --included=dev

package-lock.json 파일에 대해서는 별도 포스팅에서 자세히 다루고 있으니 참고 바랍니다.

마치면서

이상으로 자바스크립트 패키지를 설치할 때 사용되는 npm install 명령어를 어떻게 활용하는지 살펴보앗습니다. 자주 사용하시는 명령어인 만큼 이번 기회에 잘 정리해두시면 두고 두고 도움이 되실거라 생각합니다.

npm에 대한 포스팅은 관련 태그를 통해서 쉽게 만나보세요!