당신이 총주방장이라고 상상해 보십시오. 모든 체인점에서 똑같이 맛있는 요리를 만들어낼 수 있도록 일련의 ‘비법 소스’를 개발했습니다. 이 소스들을 각 지점으로 보내고 싶지만, 길가는 행인이 마음대로 가져가게 둘 수는 없습니다.

소프트웨어 개발의 세계에서 이 비법 소스는 바로 **사내 ‘프라이빗 패키지’**입니다.

프로젝트가 늘어남에 따라 이런 불만을 느껴보셨을 것입니다. 모든 프로젝트에 동일한 UI 컴포넌트나 유틸리티 함수를 복사해서 붙여넣거나, 인생의 선택을 회의하게 될 정도로 Git Submodule과 씨름하는 일 말이죠. 사실 여러분에게 필요한 것은 ‘프라이빗 팬트리(프라이빗 NPM 레지스트리)‘뿐입니다. 오늘은 pnpm을 사용하여 패키지를 GitLab에 게시하는 방법을 알아보고, 팀원들이 오픈 소스 패키지처럼 단 한 줄의 명령어로 설치할 수 있게 하는 방법을 알아보겠습니다.

왜 프라이빗 패키지와 스코프(Scope)가 필요한가요?

Node.js의 세계에서 프라이빗 패키지에는 ‘성(Surname)‘이 있어야 합니다. 이것이 바로 **스코프(Scope)**입니다.

예를 들어, 회사의 이름이 @my-company라면 패키지 이름은 @my-company/ui-kit과 같은 형식이 됩니다. 이 성이 있으면 pnpm은 npmjs.org를 무작정 뒤지는 대신, 지정된 회사의 좌표로 곧장 향하게 됩니다.

핵심 결정: 그룹 레벨 vs 프로젝트 레벨

GitLab에서는 조미료를 어디에 보관할지를 결정하는 것과 같습니다.

‘출입증’ 설정: 액세스 토큰과 환경 변수

지하 식량 창고에 들어가려면 먼저 ‘출입 카드’를 받아야 합니다.

1. GitLab의 Settings > Access Tokens로 이동합니다.
2. 토큰을 신청하고, read_api(다운로드용) 및 write_package_registry(게시용) 권한을 선택합니다.
3. 중요: 토큰을 받은 후에는 절대 코드나 .npmrc 파일에 직접 하드코딩하지 마십시오! 그것은 금고 열쇠를 문에 꽂아두는 것과 같습니다.

가장 전문적인 방법은 ‘환경 변수’에 숨기는 것입니다. Mac 또는 Linux 터미널(예: ~/.zshrc)에 다음 줄을 추가합니다.

export GITLAB_TOKEN="여러분의_GitLab_Token"

이렇게 하면 시스템이 자동으로 자격 증명을 첨부해 주어 보안과 편의를 동시에 챙길 수 있습니다.

탐색 설정: .npmrc의 핵심

다음으로, 프로젝트 루트에 탐색 지도인 .npmrc를 생성하여 pnpm에게 어디로 가야 할지 알려줍니다.

# @my-company로 시작하는 모든 것은 GitLab으로 보냅니다
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# 출입 카드 인증을 설정합니다 (방금 설정한 환경 변수 읽기)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

회사의 그룹 ID만 바꿔 넣으면 길은 열립니다!

게시 전 마지막 단계: 패키징의 기술

많은 사람들이 연결 설정을 마친 후 서둘러 게시하다가 실수로 테스트 파일이나 비밀 설정까지 함께 업로드하곤 합니다. 이때 package.json의 files 필드가 매우 유용합니다.

이것은 ‘허용 목록(Allowlist)’ 개념입니다.

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

게시하기 전에 pnpm pack 명령어를 사용하여 로컬에서 패키지 내용을 확인해 보는 것을 권장합니다. 모든 것이 확인되면 자신 있게 pnpm publish를 실행하십시오!

결론

프라이빗 팬트리를 구축하는 것은 어렵지 않습니다. 핵심 요소는 다음과 같습니다.

1. 토큰을 신청하고 환경 변수로 보호하십시오.
2. 올바른 .npmrc 탐색 지도를 구성하십시오.
3. package.json의 files 필드를 사용하여 정확하게 배송하십시오.

이 워크플로우를 익히면 회사의 코드 재사용을 전문적이고 안전하며 우아하게 만들 수 있습니다. 이제 여러분만의 중앙 주방을 만들러 가보십시오!

Reference

• package.json | npm Docs
• Package registry | GitLab Docs