노현진's Blog

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

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

Posted
By HyunJinNo

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 deploymentsourceGitHub Actions로 지정합니다.

2.2. basePath 설정하기

next.config.ts 파일에서 basePath 옵션을 설정합니다.

typescript
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 작성하기

yml
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 이름 설정하기

yml
1# workflow 이름 설정
2name: Deploy demo site to Pages

먼저 위와 같이 workflow 이름을 설정합니다. workflow 이름은 name 필드에서 설정합니다. 이 이름은 GitHub의 Actions 탭에 표시됩니다.

2.3.2. 이벤트 설정하기

yml
1# workflow를 트리거하는 이벤트 설정
2on:
3  push:
4    branches: ["main"]

on 필드에서는 workflow를 트리거하는 이벤트를 정의합니다. 가장 많이 사용하는 이벤트로는 push, pull_request 등이 있습니다. 위의 예시는 main 브랜치에 코드 푸시가 이루어질 때 workflow를 트리거합니다.

2.3.3. GITHUB_TOKEN 권한 설정하기

yml
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: readrepository 코드 읽기
pages: writePages 배포
id-token: writeOIDC 인증용

2.3.4. concurrency 설정하기

yml
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 설정하기

yml
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@v4

jobs 필드는 workflow 내에서 실행될 개별 작업을 정의합니다. 각 job은 여러 단계를 포함할 수 있으며 병렬로 실행이 가능합니다.

먼저 다음과 같이 정의할 job의 이름을 설정해야 합니다. 이름은 자유롭게 지을 수 있습니다. 저의 경우에는 빌드를 수행하는 job인 build와 배포를 수행하는 job인 deploy를 정의하였고 build 이후 deploy를 수행하도록 설정하였습니다.

yml
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@v4

Info.

needs: build는 해당 job이 수행되기 위해 먼저 완료되어야 하는 job을 지정하는 부분입니다. 즉, build가 완료된 이후에 deploy를 수행합니다.

다음으로 해당 job이 실행될 환경을 지정합니다. GitHub에서 제공하는 기본 runs-onubuntu-latest, macos-latest, windows-latest 등이 있습니다.

yml
1# Ubuntu 환경에서 실행
2runs-on: ubuntu-latest

steps 필드에는 job 내부에서 순차적으로 실행되는 개별 작업을 정의합니다. Shell 명령어를 실행하거나, GitHub에서 제공하는 액션(Action)을 사용하여 설정할 수 있습니다.

Next.js로 만든 demo 사이트를 GitHub Pages에 배포하기 위해서는 다음과 같은 step이 필요합니다.

  1. GitHub Repository에 push된 코드 가져오기
  2. Node.js 설치하기
  3. pnpm 설치하기
  4. 의존성 설치하기
  5. GitHub Pages 배포 환경 초기화하기
  6. 로컬 패키지 빌드하기
  7. demo 빌드하기
  8. 정적 파일 업로드하기
  9. GitHub Pages에 정적 배포하기

2.3.5.1. GitHub Repository에 push된 코드 가져오기

먼저 GitHub Repository에 있는 코드를 가져와야 합니다. GitHub에서 제공하는 액션으로 actions/checkout이 있으며, 해당 액션을 사용해서 Repository의 코드를 가져올 수 있습니다.

yml
1steps:
2  - name: Checkout code
3    uses: actions/checkout@v6

name 필드는 각 단계의 이름을 지정하는 부분으로, job 실행 시 로그에 표시됩니다. 이름은 해당 단계가 하고자 하는 작업을 이해할 수 있게 작성하면 됩니다. uses 필드는 GitHub에서 제공하는 액션 또는 서드파티 액션을 사용할 때 지정합니다. 예를 들어, actions/checkout@v6는 Code Repository를 체크아웃(=코드 가져오기)하는 액션입니다.

2.3.5.2. Node.js 설치하기

코드를 가져온 후에는 애플리케이션을 빌드할 수 있도록 Node.js를 설치해야 합니다. GitHub에서는 다음과 같이 Node.js를 설치할 수 있는 액션을 제공합니다. 이 때, 특정 액션에 추가 인수를 전달할 때 사용하는 with 필드를 사용하여 설치하고자 하는 Node.js 버전을 지정해야 합니다.

yml
1- name: Install Node.js
2  uses: actions/setup-node@v6
3  with:
4    # Node.js 버전 설정
5    node-version: 24

2.3.5.3. pnpm 설치하기

다음과 같은 액션을 사용하여 pnpm을 설치합니다.

yml
1- name: Setup pnpm
2  uses: pnpm/action-setup@v4

2.3.5.4. 의존성 설치하기

애플리케이션을 빌드하기 위해 pnpm install 명령어를 실행하여 의존성을 설치합니다. package.json 기반으로 node_modules 설치합니다. 여기서 사용한 run은 셸 명령어를 실행할 때 사용합니다. 이 명령어는 정의된 환경에서 실행됩니다.

yml
1- name: Install dependencies
2  run: pnpm install

2.3.5.5. GitHub Pages 배포 환경 초기화하기

yml
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 패키지만 빌드하도록 지정합니다.

yml
1- name: Build local package
2  run: pnpm --filter ./packages/react-toc run build

2.3.5.7. demo 빌드하기

--filter 옵션을 사용하여 demo를 빌드합니다.

yml
1- name: Build demo
2  run: pnpm --filter ./apps/demo run build

2.3.5.8. 정적 파일 업로드하기

yml
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에 정적 배포하기

yml
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. 참고 자료

© HyunJinNo. Some rights reserved.