NPM 배포 연대기 - 3. Github Packages

NPM 배포하기 - Github Packages

03.21, 202411 min read

Github NPM JS Component

개요

Github repo packages

Github Repository 에서 종종 보이는 이것 ! 궁금해 해보신적 있으신가요?

이번에는 포스팅은 Github Packages 에 대한 다루어 보겠습니다.

NPM Scope

여럿 패키지를 이용하다보면 다음과 같은 이름의 패키지를 종종 볼 수 있습니다.

npm i @kyechan99/react-portal

사실 그 의미를 직접적으로 찾아보진 않아도, 이러한 이름을 가진 패키지들을 여럿 보다 보면 유추할 수 있죠.

@--- 의 부분은 단체(org) 혹은 그룹이라는 것을 의미한다는 걸요.

이런식으로 스코프가 지정된 패키지를 스코프 패키지라고 부른다 볼 수 있습니다.

Emotion 을 예로 들어 볼까요?

scope package

Emotion 의 여러 패키지들을 사용하기 위해 설치한 패키지들은 스코프를 통해 Emotion 에서 제공한 공식적인 패키지임을 알 수 있습니다. 더불어 설치된 패키지는 node_modules/@emotion/ 내부에 모여 포함되어 관리됩니다.

갑자기 Scope 에 대해 이야기 하게 된 이유는... 이 뒤에 나올 Github Packages 는 이런 스코프 기반으로 관리되어서, 만약 이런 스코프가 없다면 사용할 수 없습니다.

Github Packages

바로 이 부분이 Github Packages 를 사용하고 있음을 나타내고 있습니다.

Get started with Github Packages

Publish your first package 문구를 누르면 나타나는 Github 의 화면입니다.

일반적으로 Docker 는 DockerHub, C# 은 NuGet, 우리 Node.js 는 NPM 을 통해 패키지 저장소를 사용합니다.

화면에서와 같이 Github Packages 를 통해 npm 을 구성할 수 있습니다.

생각하는짤

Github Packages 를 이용하는 이유는 저는 두 가지가 있다고 생각됩니다.

첫째는, 비공개 패키지를 관리하고자 할 때 무료라는 점입니다.

NPM.JS 에서는 비공개 패키지의 경우 매달 지불이 들어가거든요.

Github 도 과거 비공개 레포는 비용이 들었는데요... 마이크로소프트가 인수한 이후 비공개 레포 관리가 무료화가 되었었죠. 마소는 이후에도 NPM 을 인수했습니다. NPM의 비공개 관리가 Github 처럼 무료화 되지 않은 것은 아쉽긴 합니다만 자선사업은 아니니 또 어쩔 수 없는 일이겠죠. (월 $7 면 비싸다고 하기엔 모호하긴 합니다. 보통 단체에서 사용할테니까요. 다만.. 굳이..?)

billing_ghp

뭐, Github Packages 도 완전 무료는 아닙니다. 다만 허용되는 범위가 나름 널널하달까요? 당연, 기업에서 여러 패키지들이 만들어 지다 보면 넘어가겠죠. 그 경우엔 적절히 고민해 볼 수 밖에 없겠습니다.

둘째는, 아무래도 Github 을 통해 관리될 수 있단 점입니다. 앞 처럼 스코프, 즉 그룹 단위에서 관리하는 패키지의 경우 동일 organization 혹은 프로필을 통해 그 목록들을 쉽게 찾아 볼 수 있고 그만큼 관련 레포에도 접근하는 방식 등 여러 관리에 용이한 점이 존재합니다.

Token

접근 권한이 부여되었음을 인증하기 위한 토큰을 발급 받습니다.

package not found

Github Settings 페이지에서 Developer Settins 메뉴를 찾아주세요.

github_tokens_setting

Personal access token의 Tokens 메뉴에서 새 토큰을 발급받습니다.

access

이름의 경우 이 토큰이 어떤 역할을 위해 만들었는지 기억하기 쉬운 이름으로 설정하고 만료기간은 상황에 맞게 설정해주세요.

우리가 허락해 주어야 할 것은 repo,workflow, write:packages 권한입니다.

write:packages를 통해 Github Package 를 만들 수 있는 권한을 얻고요. 해당 권한을 위해서 repo 권한을 필수로 요구됩니다. workflow 권한을 통해서 Github Action 내에 사용될 GITHUB_TOKEN 이라는 값에 접근 가능하게 도와주겠습니다.

각 권한이 어떤 무엇을 허락해주는지 확인하고 싶다면 권한 설명 을 통해 확인하세요.

ghp_********

이후 토큰을 생성하면 다음과 같은 형태의 토큰을 발급됩니다. 첫 생성 이후 다시 확인할 방법은 없습니다.

Token New

package.json

{
  "name": "@kyechan99/react-portal",
  "version": "1.0.0",
  "description": "react-portal",
  "author": "kyechan99 <kyechan99@gmail.com>",
  "type": "module",
  "main": "dist/index.umd.cjs",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/kyechan99/react-portal/issues"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/kyechan99/react-portal.git"
  },
  "homepage": "https://github.com/kyechan99/react-portal",
  "keywords": ["react", "react-portal"]
  //...
}

만든 패키지에 알맞게 데이터들을 작성해줍니다.

위에서 그나마 keywords 나 bugs 를 제외하고 그 나머지는 모두 작성해야 합니다.

package.json

{
  //...
  "publishConfig": {
    "@kyechan99:registry": "https://npm.pkg.github.com"
  }
}

publishConfig 에 스코프 registry 값을 입력하면서 publish 를 위한 설정을 진행합니다.

.npmrc

@kyechan99:registry=https://npm.pkg.github.com

.npmrc 설정 파일에 다음과 같이 작성함으로써 대신할 수도 있습니다.

인증

GitHub Packages에 패키지를 게시하고 또 사용하기 위해 설치하려면 앞서 발급한 개인 액세스 토큰(Personal Access Token)을 사용해야 합니다.

.npmrc

//npm.pkg.github.com/:_authToken=TOKEN

앞서 잠깐 등장했지만 .npmrc 파일을 사용하면 다른 개발자의 실수로 GitHub 패키지 대신 npmjs.org에 패키지를 게시하는 것을 방지할 수 있습니다. 파일로 설정을 저장하기 때문에 다른 환경에서의 미연의 실수를 방지할 수 있는 거죠.

물론 이 방법 역시 .npmrc 가 아닌 login 방법으로도 사용가능합니다.

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN      # 발급받은 토큰 값

Action

Github Action 을 이용해 배포하도록 하겠습니다.

.github/workflows/release-package.yml

name: Release Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'

      - name: Install pnpm
        run: |
          npm install -g pnpm

      - name: Install Packages
        run: pnpm install

      - run: pnpm buildOnce

      - run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

위 코드는 pnpm 기반이며 상황과 사람에 따라 다를 수 있습니다.

Action 의 발동 조건은 Release 가 생성되었을 때로 지정합니다.

다른 경우로 설정하는 것에는 물론 상관은 없습니다만 패키지를 업데이트를 하는경우는 대체로 새 릴리즈가 생성되었을 때입니다.

그러니 배포 액션을 매 순간마다 호출하는 것을 불필요한 일이겠죠?

더불어 package.json 의 version 변경을 하는 일 역시도 새 릴리즈를 생성했을 때 이니까요. git tag 생성만으로 이 version up 을 진행해주는 Action 도 있는 듯 하니 참고하셔도 괜찮을 것 같습니다.

이후 사용

release

정상적으로 작동되었다면 Github Repo, 혹은 프로필의 Packages 메뉴 등에서 게시된 패키지를 확인할 수 있습니다.

package not found

게시는 정상적으로 되었는데 다른 프로젝트에서 해당 패키지를 설치할 수 없는 에러가 나타나나요?

.npmrc

@kyechan99:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN          # 비공개 패키지 접근 권한

이때 .npmrc 파일에 입력한 토큰으로 비공개 패키지에 접근하여 설치되게끔 해결 할 수 있습니다.

공개 패키지라면 접근을 위한 토큰은 별도로 필요하지 않습니다.

.npmrc

@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com

일반적으로 Github Packages 는 하나의 스코프 (organization) 를 사용할 수 있지만 여러 줄로 입력하여 복수의 organization 이나 유저의 패키지를 사용 할 수도 있습니다.

틀린 내용이 있다면 지적해 주시고,
더 좋은 방법이나 생각을 공유해주세요.