DevelopNode.js

npmrc 설정 정리

, ,

npmrc 설정 정리

npm 의 동작 방식을 제어하는 설정 파일인 .npmrc 의 주요 설정과 실무 활용 방법을 정리한다.

.npmrc 는 npm 의 동작을 제어하는 설정 파일이다.
레지스트리 주소, 인증 토큰, 패키지 설치 경로 등 다양한 설정을 담을 수 있으며, 프로젝트별로도 적용이 가능하다.

npmrc 파일의 위치

.npmrc 파일은 여러 위치에 존재할 수 있으며, npm 은 이를 우선순위 순서로 읽는다.

우선순위 위치 설명
1 프로젝트 루트 (/path/to/project/.npmrc) 프로젝트별 설정. 팀 공유 가능
2 유저 홈 디렉토리 (~/.npmrc) 개인 사용자 전용 설정
3 전역 설정 ($PREFIX/etc/npmrc) 시스템 전역 설정
4 npm 내장 설정 npm 바이너리에 포함된 기본값

우선순위가 높을수록 나중에 읽어 덮어쓴다.
즉, 프로젝트 루트의 .npmrc 가 유저 홈의 설정보다 우선 적용된다.

현재 적용 중인 설정은 다음 명령으로 확인할 수 있다.

npm config list

주요 설정 항목

registry

패키지를 다운받을 레지스트리 주소를 설정한다.

registry=https://registry.npmjs.org/

사내 Nexus, Artifactory, Verdaccio 같은 사설 레지스트리를 사용할 때 바꿔준다.

registry=https://my-private-registry.example.com/

스코프(@scope) 별로 다른 레지스트리를 지정하는 것도 가능하다.
공개 패키지는 npm 공식 레지스트리를 유지하고, 사내 패키지만 별도 레지스트리를 사용할 때 유용하다.

@mycompany:registry=https://my-private-registry.example.com/

authToken

레지스트리 인증에 사용하는 토큰이다.
사설 레지스트리나 npm 유료 플랜의 프라이빗 패키지에 접근할 때 필요하다.

//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxx

스코프별 레지스트리에 별도 토큰을 설정할 수 있다.

//my-private-registry.example.com/:_authToken=my-private-token

주의: 인증 토큰을 .npmrc 에 직접 하드코딩하면 git 에 커밋될 위험이 있다.
프로젝트 .npmrc 에는 환경변수 참조를 사용하고, 실제 토큰은 CI/CD 환경변수로 관리하는 것이 안전하다.

//my-private-registry.example.com/:_authToken=${NPM_TOKEN}

save-exact

패키지를 설치할 때 package.json 에 정확한 버전을 기록할지 여부를 설정한다.

save-exact=true

기본값은 false 이며, ^1.2.3 처럼 범위 버전으로 저장된다.
true 로 설정하면 1.2.3 처럼 정확한 버전으로 저장된다.
버전 고정이 중요한 프로덕션 프로젝트에서 유용하다.

legacy-peer-deps

npm v7 이상에서 peer dependency 충돌이 발생할 때 설치를 계속 진행할지 여부를 설정한다.

legacy-peer-deps=true

일부 구버전 패키지에서 peer dependency 충돌이 발생할 때 임시 해결책으로 사용하지만, 가능하면 근본적인 패키지 업데이트를 통해 해결하는 것이 낫다.

fund

패키지 설치 후 펀딩 메시지 출력 여부를 설정한다.

fund=false

CI/CD 환경에서는 불필요한 출력이므로 꺼두는 경우가 많다.

audit

패키지 설치 시 취약점 검사 여부를 설정한다.

audit=false

CI/CD 성능 최적화를 위해 끄는 경우가 있지만, 보안상 켜두는 것이 권장된다.

cache

npm 캐시 디렉토리 경로를 설정한다.

cache=/tmp/npm-cache

CI/CD 환경에서 캐시 디렉토리를 지정해 의존성 캐싱을 제어할 때 사용한다.

engine-strict

package.json 의 engines 필드와 현재 Node.js 버전이 맞지 않으면 설치를 실패시킨다.

engine-strict=true

프로젝트에서 Node.js 버전을 강제해야 할 때 유용하다.

실무 활용 패턴

사설 레지스트리 + 토큰 설정 (CI/CD)

사내 Nexus나 Artifactory 같은 사설 레지스트리를 사용하는 환경에서는 다음처럼 .npmrc 를 구성하는 경우가 많다.

registry=https://my-private-registry.example.com/
//my-private-registry.example.com/:_authToken=${NPM_TOKEN}

토큰 값은 CI/CD 시스템의 시크릿 또는 환경변수로 주입한다.
${NPM_TOKEN} 형태로 환경변수를 참조하면 파일에 토큰을 하드코딩하지 않아도 된다.

스코프별 레지스트리 혼용

공개 패키지는 npm 공식 레지스트리, 사내 패키지는 사설 레지스트리를 사용하는 경우이다.

registry=https://registry.npmjs.org/
@mycompany:registry=https://my-private-registry.example.com/
//my-private-registry.example.com/:_authToken=${NPM_TOKEN}

이렇게 하면 npm install @mycompany/ui-kit 은 사설 레지스트리에서 가져오고, 나머지 공개 패키지는 npm 공식 레지스트리에서 가져온다.

CI/CD 최적화

CI/CD 환경에서는 불필요한 출력을 줄이고 속도를 높이기 위한 설정을 추가하기도 한다.

fund=false
audit=false
progress=false

npmrc 관련 명령어

설정을 CLI 로 조작하거나 확인할 때는 npm config 명령을 사용한다.

# 현재 설정 전체 조회
npm config list

# 특정 설정 값 조회
npm config get registry

# 설정 변경 (유저 홈 .npmrc 에 저장)
npm config set registry https://my-private-registry.example.com/

# 설정 삭제
npm config delete registry

주의사항

  • .npmrc 를 프로젝트에 포함할 때는 토큰이나 민감한 정보가 없는지 반드시 확인한다.
  • 환경변수 참조(${VAR}) 방식을 사용하면 .npmrc 파일 자체를 git 에 커밋해도 토큰 유출 위험을 낮출 수 있다.
  • .gitignore 에 .npmrc 를 추가하면 파일 자체를 커밋하지 않는 방법도 있지만, 그러면 팀원들과 설정을 공유하기 어렵다.
    따라서 민감하지 않은 설정은 .npmrc 에 두고, 토큰만 환경변수로 관리하는 방식이 현실적이다.

정리

.npmrc 는 npm 동작을 세밀하게 제어할 수 있는 설정 파일이다.

  • 레지스트리 주소는 registry 로 설정한다.
  • 스코프별 레지스트리는 @scope:registry 로 지정한다.
  • 인증 토큰은 하드코딩하지 말고 ${환경변수} 참조 방식을 사용한다.
  • 프로젝트 루트 .npmrc 는 팀 공유 설정으로 활용하고, 민감한 값은 CI/CD 시크릿으로 관리한다.
  • npm config list 로 현재 적용 중인 설정을 언제든지 확인할 수 있다.
Share