노현진's Blog

pnpm + tsdown으로 React 라이브러리 만들기 ④ - 라이브러리 배포

pnpm + tsdown으로 React 라이브러리를 만드는 과정에서 라이브러리 배포 방법에 대해 정리한 페이지입니다.

Posted
By HyunJinNo

Tags

monorepo, OIDC, pnpm, React, Release Please, tsdown

Environment

pnpm v10.32.1

react v19.2.3

tsdown v0.21.3

@tsdown/css v0.21.4

1. 개요

pnpm + tsdown으로 React 라이브러리를 만드는 방법에 대해 정리한 페이지입니다.

총 5개의 Part로 분리하여 작성하였으며, 이 페이지에서는 라이브러리 배포 과정을 다룹니다.

2. 라이브러리 수동 배포하기

2.1. npm 회원가입하기

npm | Home에 접속하여 회원가입을 진행합니다.

2.2. npm 로그인하기

다음 명령어를 입력하여 npm에 로그인합니다.

bash
1npm login

2.3. npm에 수동 배포하기

배포하려는 라이브러리 패키지에서 다음 명령어를 입력하여 npm에 라이브러리를 배포합니다.

bash
1npm publish --access public

--access public 옵션은 공개 패키지를 배포할 때 사용합니다. 이 옵션을 생략하면 기본적으로 개인 패키지로 배포됩니다.

3. 라이브러리 자동 배포하기

이 문단에서는 GitHub Actions로 라이브러리를 자동 배포하는 과정을 설명합니다. 이 문단에서 다루는 라이브러리 자동 배포 과정은 다음과 같습니다.

  1. GitHub Repository에 라이브러리 코드를 push
  2. Release Please를 통해 Release PR 생성
  3. PR merge 이후 Tag 생성 및 라이브러리를 자동 배포

npm에 라이브러리를 자동 배포하기 위해선 Granular Access Token 또는 OIDC 방식을 사용할 수 있습니다. Granular Access Token의 경우 만료 기간이 지나면 다시 생성해야 하므로, 이 문단에서는 OIDC 방식을 사용할 예정이며, 이를 위해 먼저 npm에 라이브러리가 배포되어 있는 상태여야 합니다.

3.1. OIDC (OpenID Connect) 설정하기

먼저 다음과 같이 배포된 라이브러리 페이지에 접속하여 Settings 탭을 클릭합니다.

이후 다음과 같이 Trusted Publisher를 등록합니다.

마지막으로 Publishing access 항목에서 Require two-factor authentication and disallow tokens (recommended) 을 선택하고 패키지 설정을 업데이트합니다.

3.2. release-please.yml 생성하기

.github/workflows 디렉토리에 release-please.yml 파일을 생성한 후 다음과 같이 작성합니다.

yml
1# workflow 이름 설정
2name: Release Please
3
4# workflow를 트리거하는 이벤트 설정
5on:
6  push:
7    branches: ["main"]
8
9permissions:
10  contents: write
11  issues: write
12  pull-requests: write
13
14# 실행할 jobs 설정
15jobs:
16  release-please:
17    # Ubuntu 환경에서 실행
18    runs-on: ubuntu-latest
19
20    steps:
21      - name: Run Release Please
22        uses: googleapis/release-please-action@v4
23        with:
24          release-type: node
25          path: packages/react-toc
26          token: ${{ secrets.PAT }}

위의 workflow에서 중요한 부분은 바로 token 설정 부분입니다. Release Please는 기본적으로 GITHUB_TOKEN을 사용하지만, GITHUB_TOKEN으로 발생한 이벤트는 다른 workflow를 트리거하지 않습니다. 따라서 PAT이라는 Personal Access Token을 사용해야 합니다.

3.3. Personal Access Token 생성하기

PAT을 사용하려면 GitHub에서 Personal Access Token을 생성해야 합니다. 먼저 GitHub에서 로그인 한 후, 본인의 프로필을 클릭해 Settings > Developer settings 로 이동합니다.

다음으로 Personal access tokens > Fine-grained tokens > Generator new token 을 순서대로 클릭합니다.

아래와 같은 페이지에서 Personal Access Token을 생성할 수 있습니다. Permissions 항목에서 Actions, Contents, Pull requests를 선택하고 Access:Read and Write를 선택합니다. Metadata는 Actions 선택 시 자동으로 추가됩니다.

Generate token 버튼을 클릭하면 Personal Access Token이 생성됩니다. 주의할 점은 해당 페이지에서 보이는 토큰은 다시 볼 수 없으므로 토큰을 복사하여 보관해야 합니다.

3.4. GitHub Secrets 설정하기

생성한 Personal Access Token을 GitHub Actions에서 사용하려면 GitHub Secrets에 추가해야 합니다. 다음과 같이 GitHub Repository 내에서 Settings > Secrets and variable > Actions로 이동합니다.

이후 New repository secret 버튼을 클릭하여 새로운 secret을 생성합니다. Name을 PAT으로, 내용에는 복사한 Personal Access Token을 붙여넣으면 됩니다.

3.5. publish.yml 생성하기

.github/workflows 디렉토리에 publish.yml 파일을 생성한 후 다음과 같이 작성합니다.

yml
1# workflow 이름 설정
2name: Publish to npm
3
4# workflow를 트리거하는 이벤트 설정
5on:
6  push:
7    tags:
8      - "v*"
9
10permissions:
11  id-token: write # Required for OIDC
12  contents: write
13
14# 실행할 jobs 설정
15jobs:
16  publish:
17    # Ubuntu 환경에서 실행
18    runs-on: ubuntu-latest
19
20    steps:
21      - name: Checkout code
22        uses: actions/checkout@v6
23
24      - name: Setup pnpm
25        uses: pnpm/action-setup@v4
26
27      - name: Install Node.js
28        uses: actions/setup-node@v6
29        with:
30          # Node.js 버전 설정
31          node-version: 24
32          registry-url: "https://registry.npmjs.org"
33          cache: "pnpm"
34
35      - name: Install dependencies
36        run: pnpm install --frozen-lockfile
37
38      - name: Build local package
39        run: pnpm --filter ./packages/react-toc run build
40
41      - name: Publish to npm
42        run: pnpm --filter ./packages/react-toc publish --access public --no-git-checks --provenance

위의 workflow 설정 중 중요한 부분에 대해 설명하자면 다음과 같습니다.

3.5.1. permissions

yml
1permissions:
2  id-token: write # Required for OIDC
3  contents: write

OIDC 방식을 사용하기 위해 id-token: write permission이 반드시 필요합니다.

3.5.2. --provenance

yml
1- name: Publish to npm
2  run: pnpm --filter ./packages/react-toc publish --access public --no-git-checks --provenance

라이브러리를 npm에 배포하는 부분입니다. --provenance 옵션을 사용하면 npm에 "이 패키지가 GitHub Actions에서 만들어졌다"는 보안 서명을 추가할 수 있습니다.

3.6. 라이브러리 자동 배포 결과

라이브러리를 자동 배포한 결과는 다음과 같습니다.

4. 다음 Part

다음 글에서는 GitHub Pages에 demo를 정적 배포하는 과정을 다룹니다.

5. demo 배포하기

5. 참고 자료

Front-end
monorepooidcpnpmreactrelease-pleasetsdown
This post is licensed under CC BY 4.0 by the author.
공유하기:

© HyunJinNo. Some rights reserved.