pnpm + tsdown으로 React 라이브러리 만들기 ⑤ - demo 배포
pnpm + tsdown으로 React 라이브러리를 만드는 과정에서 demo 배포 방법에 대해 정리한 페이지입니다.
Tags
CI, CD, GitHub, GitHub Actions, GitHub Pages, monorepo, Nextra, Next.js, pnpm, React, Static Export, tsdown, YML
Environment
pnpm v10.32.1
nextra v4.6.1
Next.js v16.1.6
react v19.2.3
tsdown v0.21.3
@tsdown/css v0.21.4
1. 개요
pnpm + tsdown으로 React 라이브러리를 만드는 방법에 대해 정리한 페이지입니다.
총 5개의 Part로 분리하여 작성하였으며, 이 페이지에서는 demo 배포 과정을 다룹니다.
2. demo 배포하기
전체적인 과정은 Next.js GitHub Pages 정적 배포하기 페이지에서 다루었던 내용과 유사하므로 참고하시면 좋습니다.
2.1. GitHub Pages 설정하기
GitHub Pages로 배포하기 위해 먼저 Repository에서 Settings > Pages로 이동한 후
Build and deployment의 source를 GitHub Actions로 지정합니다.
2.2. basePath 설정하기
next.config.ts 파일에서 basePath 옵션을 설정합니다.
1import type { NextConfig } from "next";
2import nextra from "nextra";
3
4const nextConfig: NextConfig = {
5 /* config options here */
6 reactCompiler: true,
7 output: "export",
8 basePath: "/react-toc",
9 images: {
10 unoptimized: true,
11 },
12};
13
14const withNextra = nextra({
15 // ... other Nextra config options
16});
17
18export default withNextra({
19 ...nextConfig,
20 turbopack: {
21 resolveAlias: {
22 // Path to your `mdx-components` file with extension
23 "next-mdx-import-source-file": "./src/mdx-components.tsx",
24 },
25 },
26});2.3. Workflow 작성하기
1# workflow 이름 설정
2name: Deploy demo site to Pages
3
4# workflow를 트리거하는 이벤트 설정
5on:
6 push:
7 branches: ["main"]
8
9# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
10permissions:
11 contents: read
12 pages: write
13 id-token: write
14
15# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
16# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
17concurrency:
18 group: "pages"
19 cancel-in-progress: false
20
21# 실행할 jobs 설정
22jobs:
23 # Build job
24 build:
25 # Ubuntu 환경에서 실행
26 runs-on: ubuntu-latest
27
28 steps:
29 - name: Checkout code
30 uses: actions/checkout@v6
31
32 - name: Install Node.js
33 uses: actions/setup-node@v6
34 with:
35 # Node.js 버전 설정
36 node-version: 24
37
38 - name: Setup pnpm
39 uses: pnpm/action-setup@v4
40
41 - name: Install dependencies
42 run: pnpm install
43
44 - name: Setup Pages
45 id: setup_pages
46 uses: actions/configure-pages@v5
47
48 - name: Build local package
49 run: pnpm --filter ./packages/react-toc run build
50
51 - name: Build demo
52 run: pnpm --filter ./apps/demo run build
53
54 - name: Upload artifact
55 uses: actions/upload-pages-artifact@v4
56 with:
57 path: apps/demo/out
58
59 # Deployment job
60 deploy:
61 needs: build
62 environment:
63 name: github-pages
64 url: ${{ steps.deployment.outputs.page_url }}
65 runs-on: ubuntu-latest
66 steps:
67 - name: Deploy to GitHub Pages
68 id: deployment
69 uses: actions/deploy-pages@v4위의 workflow 설정에 대해 설명하자면 다음과 같습니다.
2.3.1. workflow 이름 설정하기
1# workflow 이름 설정
2name: Deploy demo site to Pages먼저 위와 같이 workflow 이름을 설정합니다.
workflow 이름은 name 필드에서 설정합니다. 이 이름은 GitHub의 Actions 탭에 표시됩니다.
2.3.2. 이벤트 설정하기
1# workflow를 트리거하는 이벤트 설정
2on:
3 push:
4 branches: ["main"]on 필드에서는 workflow를 트리거하는 이벤트를 정의합니다.
가장 많이 사용하는 이벤트로는 push, pull_request 등이 있습니다.
위의 예시는 main 브랜치에 코드 푸시가 이루어질 때 workflow를 트리거합니다.
2.3.3. GITHUB_TOKEN 권한 설정하기
1# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
2permissions:
3 contents: read
4 pages: write
5 id-token: write위와 같이 GITHUB_TOKEN 권한을 설정해야 합니다. 권한 설정을 해야 GitHub Pages에 배포할 수 있습니다.
| 권한 | 이유 |
|---|---|
| contents: read | repository 코드 읽기 |
| pages: write | Pages 배포 |
| id-token: write | OIDC 인증용 |
2.3.4. concurrency 설정하기
1# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
2# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
3concurrency:
4 group: "pages"
5 cancel-in-progress: false동시에 여러 배포가 실행되지 않도록 방지하는 부분으로, 이전 배포는 취소하지 않습니다.
2.3.5. Job 설정하기
1# 실행할 jobs 설정
2jobs:
3 # Build job
4 build:
5 # Ubuntu 환경에서 실행
6 runs-on: ubuntu-latest
7
8 steps:
9 - name: Checkout code
10 uses: actions/checkout@v6
11
12 - name: Install Node.js
13 uses: actions/setup-node@v6
14 with:
15 # Node.js 버전 설정
16 node-version: 24
17
18 - name: Setup pnpm
19 uses: pnpm/action-setup@v4
20
21 - name: Install dependencies
22 run: pnpm install
23
24 - name: Setup Pages
25 id: setup_pages
26 uses: actions/configure-pages@v5
27
28 - name: Build local package
29 run: pnpm --filter ./packages/react-toc run build
30
31 - name: Build demo
32 run: pnpm --filter ./apps/demo run build
33
34 - name: Upload artifact
35 uses: actions/upload-pages-artifact@v4
36 with:
37 path: apps/demo/out
38
39 # Deployment job
40 deploy:
41 needs: build
42 environment:
43 name: github-pages
44 url: ${{ steps.deployment.outputs.page_url }}
45 runs-on: ubuntu-latest
46 steps:
47 - name: Deploy to GitHub Pages
48 id: deployment
49 uses: actions/deploy-pages@v4jobs 필드는 workflow 내에서 실행될 개별 작업을 정의합니다. 각 job은 여러 단계를 포함할 수 있으며 병렬로 실행이 가능합니다.
먼저 다음과 같이 정의할 job의 이름을 설정해야 합니다. 이름은 자유롭게 지을 수 있습니다.
저의 경우에는 빌드를 수행하는 job인 build와 배포를 수행하는 job인 deploy를 정의하였고
build 이후 deploy를 수행하도록 설정하였습니다.
1# 실행할 jobs 설정
2jobs:
3 # Build job
4 build:
5 runs-on: ubuntu-latest
6
7 # ...
8
9 # Deployment job
10 deploy:
11 needs: build
12 environment:
13 name: github-pages
14 url: ${{ steps.deployment.outputs.page_url }}
15 runs-on: ubuntu-latest
16 steps:
17 - name: Deploy to GitHub Pages
18 id: deployment
19 uses: actions/deploy-pages@v4Info.
needs: build는 해당 job이 수행되기 위해 먼저 완료되어야 하는 job을 지정하는 부분입니다. 즉, build가 완료된 이후에 deploy를 수행합니다.
다음으로 해당 job이 실행될 환경을 지정합니다.
GitHub에서 제공하는 기본 runs-on는 ubuntu-latest, macos-latest, windows-latest 등이 있습니다.
1# Ubuntu 환경에서 실행
2runs-on: ubuntu-lateststeps 필드에는 job 내부에서 순차적으로 실행되는 개별 작업을 정의합니다.
Shell 명령어를 실행하거나, GitHub에서 제공하는 액션(Action)을 사용하여 설정할 수 있습니다.
Next.js로 만든 demo 사이트를 GitHub Pages에 배포하기 위해서는 다음과 같은 step이 필요합니다.
- GitHub Repository에 push된 코드 가져오기
- Node.js 설치하기
- pnpm 설치하기
- 의존성 설치하기
- GitHub Pages 배포 환경 초기화하기
- 로컬 패키지 빌드하기
- demo 빌드하기
- 정적 파일 업로드하기
- GitHub Pages에 정적 배포하기
2.3.5.1. GitHub Repository에 push된 코드 가져오기
먼저 GitHub Repository에 있는 코드를 가져와야 합니다. GitHub에서 제공하는 액션으로 actions/checkout이 있으며, 해당 액션을 사용해서 Repository의 코드를 가져올 수 있습니다.
1steps:
2 - name: Checkout code
3 uses: actions/checkout@v6name 필드는 각 단계의 이름을 지정하는 부분으로, job 실행 시 로그에 표시됩니다.
이름은 해당 단계가 하고자 하는 작업을 이해할 수 있게 작성하면 됩니다.
uses 필드는 GitHub에서 제공하는 액션 또는 서드파티 액션을 사용할 때 지정합니다.
예를 들어, actions/checkout@v6는
Code Repository를 체크아웃(=코드 가져오기)하는 액션입니다.
2.3.5.2. Node.js 설치하기
코드를 가져온 후에는 애플리케이션을 빌드할 수 있도록 Node.js를 설치해야 합니다.
GitHub에서는 다음과 같이 Node.js를 설치할 수 있는 액션을
제공합니다. 이 때, 특정 액션에 추가 인수를 전달할 때 사용하는 with 필드를 사용하여 설치하고자 하는 Node.js 버전을 지정해야 합니다.
1- name: Install Node.js
2 uses: actions/setup-node@v6
3 with:
4 # Node.js 버전 설정
5 node-version: 242.3.5.3. pnpm 설치하기
다음과 같은 액션을 사용하여 pnpm을 설치합니다.
1- name: Setup pnpm
2 uses: pnpm/action-setup@v42.3.5.4. 의존성 설치하기
애플리케이션을 빌드하기 위해 pnpm install 명령어를 실행하여 의존성을 설치합니다.
package.json 기반으로 node_modules 설치합니다.
여기서 사용한 run은 셸 명령어를 실행할 때 사용합니다. 이 명령어는 정의된 환경에서 실행됩니다.
1- name: Install dependencies
2 run: pnpm install2.3.5.5. GitHub Pages 배포 환경 초기화하기
1- name: Setup Pages
2 id: setup_pages
3 uses: actions/configure-pages@v5로컬 패키지와 demo 빌드 전, GitHub Pages 배포 환경을 초기화합니다.
2.3.5.6. 로컬 패키지 빌드하기
--filter 옵션을 사용하여 로컬 패키지를 빌드합니다.
--filter 옵션은 monorepo에서 특정 패키지만 빌드할 때 유용합니다.
아래의 --filter 옵션은 ./packages/react-toc 패키지만 빌드하도록 지정합니다.
1- name: Build local package
2 run: pnpm --filter ./packages/react-toc run build2.3.5.7. demo 빌드하기
--filter 옵션을 사용하여 demo를 빌드합니다.
1- name: Build demo
2 run: pnpm --filter ./apps/demo run build2.3.5.8. 정적 파일 업로드하기
1- name: Upload artifact
2 uses: actions/upload-pages-artifact@v4
3 with:
4 path: ./out./out 폴더를 GitHub Pages 서버로 업로드합니다.
2.3.5.9. GitHub Pages에 정적 배포하기
1# Deployment job
2deploy:
3 needs: build
4 environment:
5 name: github-pages
6 url: ${{ steps.deployment.outputs.page_url }}
7 runs-on: ubuntu-latest
8 steps:
9 - name: Deploy to GitHub Pages
10 id: deployment
11 uses: actions/deploy-pages@v4마지막으로 빌드된 결과물을 GitHub Pages에 정적 배포합니다.
여기서 environment 부분은 GitHub UI에 배포 URL 표시하는 부분입니다.
2.4. demo 정적 배포 결과
demo 정적 배포 결과는 다음과 같습니다.
3. 참고 자료
- React+typescript 컴포넌트 라이브러리 생성하기 ③rollup 설정 — 콩부합시다
- 고티켓-react 컴포넌트 라이브러리 만들기(3)-rollup — 이찬진 컴퓨터 교실
- esbuild vs rollup vs webpack vs tsup | "웹 자바스크립트 번들러" npm 패키지 비교
- 리액트 컴포넌트 라이브러리를 빌드하고 배포하는 방법 — React와 TypeScript를 좋아하는 개발자
- 리액트 라이브러리 npm에 배포하기 with rollup
- rolldown/tsdown: The elegant bundler for libraries powered by Rolldown
- Nextra - Next.js Static Site Generator
- HyunJinNo/react-toc: A library that automatically generates a Table of Contents (TOC) from your headings with scroll tracking.