Publishing NPM Package with ChangeSet

Opening

사내 프로젝트에서 CesiumJS 를 보다 편하게 사용하기 위해서 만들었던 여러 기능들을 개인적으로 정리해보려다가 Browser Compatibility(브라우저 호환성), Documentation, Versioning, CI/CD, npm publishing, 마지막으로 GitHub Pages Deployment 까지. 생각나는 가능한 모든 자동화를 도입해서 개발 환경을 구축한 기록을 남겨본다.

Package Metadata

일반적인 프론트 프로젝트의 경우는 패키지를 다운 받아 사용하기만 하고 배포하지 않기 때문에 package.json 에 명시되는 metadata 를 신경 쓸 일이 없다. 하지만 npm 패키지 형태로 관리 및 사용하려는 경우는 패키지의 이름부터 버전, exports 등 구체적으로 명시해줘야 하는 metadata 가 많다. Configuring npm 에서 모든 항목을 확인할 수 있다.

package.json

1{
2  "name": "@(scope)/(package-name)",
3  "version": "0.0.2",
4  "description": "package description",
5  "keywords": [],
6  "repository": {
7    "type": "git",
8    "url": "(github path)"
9  },
10  "homepage": "(homepage path)",
11  "bugs": {
12    "url": "(bug/issues report page path)"
13  },
14  "license": "MIT",
15  "author": {
16    "name": "(author name)",
17    "url": "(author homepage path)"
18  },
19  "peerDependencies": {
20    "cesium": "^1"
21  },
22}

필수로 명시해야 하는 것은 다음 두 가지가 있다.

name: 패키지의 이름으로, npm 에 publish 하기 위해서는 사용할 npm 계정에 publish 권한이 있는 scope 를 지정해주어야 한다. 개인 계정의 경우, username 과 같은 scope 는 기본으로 권한이 주어진다.
version: npm 은 semver 모듈로 패키지의 버전을 판단하기 때문에 형식을 맞춰주어야 한다. 이는 Semantic Versioning 규칙을 따르는 것으로, 이 프로젝트에서는 후술할 Changesets versioning 툴을 사용했다.

Project Configurations

TypeScript - Builds

기본 컴파일러인 tsc 를 사용해도 되지만, tsup 이라는 번들러를 이용했다. (그냥)

tsup.config.js

1import { defineConfig } from 'tsup';
2
3export default defineConfig({
4  clean: true,
5  dts: true,
6  entry: ['src/index.ts'],
7  esbuildOptions(options) {
8    options.platform = 'neutral';
9  },
10  format: ['cjs', 'esm'],
11  minify: true,
12  outExtension({ format }) {
13    return {
14      js: format === 'cjs' ? '.cjs' : '.js',
15    };
16  },
17  sourcemap: false,
18});
19

Common JS 와 Module JS (ESM) 두 가지 방식으로 컴파일을 진행했고, dts 파일을 제공하기 때문에 minify 를 true 로 설정했다. dist 디렉토리에 생성되는 빌드 결과물을 package.json 에서 제대로 명시해주어야 한다.

package.json

1{
2// ...
3  "type": "module",
4  "main": "dist/index.js",
5  "module": "dist/index.js",
6  "files": [
7    "dist"
8  ],
9  "types": "dist/index.d.ts",
10  "exports": {
11    ".": {
12      "types": "./dist/index.d.ts",
13      "import": "./dist/index.js",
14      "require": "./dist/index.cjs",
15      "default": "./dist/index.js"
16    }
17  },
18// ...
19}

type: 패키지 내에서 JavaScript 의 기본 확장자인 .js 를 어떻게 취급할지를 명시한다. module 이면 esm, common 이면 common js 로 취급한다.
main: 패키지의 기본 primary entry point.
module: 패키지를 esm 방식으로 접근할 때의 primary entry point.
files: 패키지가 포함하는 파일들로, .gitignore 의 반대격.
types: 패키지에 대한 type 을 추론할 수 있는 declaration (dts) 파일.
exports: main 에서 명시한 entry point 를 상세하게 나눠 명시하는 항목으로, require(Common JS) 로 접근하면 .cjs 파일을 참고하게 하는 것 등이 가능.

TypeScript - Documentation

JavaScript 는 JSDoc 이라는 documentation 양식이 있다. TypeScript 에서도 동일한 양식을 사용한다.

tsdoc.ts

1// TypeScript Documentation Example
2/**
3 * Abstract class that enhances Cesium collection objects with tagging functionality.
4 * This class provides a consistent API for working with different types of Cesium collections
5 * and allows grouping and manipulating collection items by custom tags.
6 *
7 * @abstract
8 * @template C - The type of Cesium collection (e.g., EntityCollection, PrimitiveCollection)
9 * @template I - The type of items in the collection (e.g., Entity, Primitive)
10 * @example
11 * ...
12 */
13abstract class Collection<C, I>{
14  ...
15}

TypeScript JSDoc 에서 지원 및 미지원 태그를 확인할 수 있다. TypeScript 는 JSDoc 의 타입 표시를 생략한다. JSDoc 을 잘 작성하면 IDE 내에서 설명을 제공할 수 있을 뿐만 아니라, API 문서까지도 자동화해서 제공할 수 있다.

TypeDoc 은 대표적인 Documentation Tool 중 하나이다. JSDoc 형태의 Comment 들을 정적으로 serve 할 수 있는 html 로 작성해준다. MarkDown(MD) 형식도 지원하기에 API 문서를 어떻게 제공할 지에 따라 선택할 수 있다. typedoc.json 로 Configuration 을 설정할 수 있으며 Typedoc Themes 에서는 사용할 수 있는 스타일 테마 플러그인과 커스텀 테마 작성 방법에 대해 안내하고 있다.

typedoc.json

1{
2  "$schema": "https://typedoc.org/schema.json",
3  "entryPoints": ["src/index.ts"],
4  "out": "docs",
5  "name": "Name of this document",
6  "includeVersion": true,
7  "excludePrivate": false,
8  "excludeProtected": false,
9  "excludeExternals": true,
10  "readme": "README.md",
11  "githubPages": true,
12  "categorizeByGroup": true,
13  "navigationLinks": {
14    "GitHub": "Link to your project",
15    "NPM": "Link to your package"
16  }
17}

위 설정대로 local 환경에서 typedoc 을 실행하면 src/index.ts 파일이 포함하고 있는 코드의 JSDoc 에 대한 API Document 가 docs 디렉토리 하위에 생성된다. 그 중 index.html 을 라이브 서버 로 실행해보면 Cesium Utils 와 같이 API Document 가 구성되는 것을 확인해볼 수 있다.

Versioning - Changesets

npm 의 Semantic Versioning 규칙을 따르면서 사용자들에게 패치노트 같은 정보를 제공해주기 위한 versioning 툴을 사용했다. 배포 및 Documentation 자동화를 위한 GitHub Actions 의 핵심 trigger 역할을 하도록 설계해서 이벤트 시점을 조절하는 것이 중요했는데, 이렇게 설계한 것에는 몇 가지 이유가 있다.

npm publish 는 package.json 의 name 과 version 이 primary key 로 작용한다. 같은 패키지 이름으로 이미 존재하는 버전으로는 다시 publish 할 수 없다.
Changeset 은 Changeset Actions 를 통해 CHANGELOG.md 의 내용을 수정할 수 있는데, Changeset 의 타입(patch/minor/major) 에 따라 package.json 의 version 을 함께 업데이트 하는 Pull Request 를 생성하도록 설정할 수 있다.
typedoc 으로 생성한 API Documentation 에는 패키지의 version 을 표시할 수 있는데, 이는 TypeDoc 실행 시점의 package.json version 을 기준으로 한다.

이런 점들을 고려해서 배포 과정을 자동화하되, 다음과 같은 배포 process 를 설계했다.

코드의 수정과 함께 주요 변경점을 담은 changeset 을 만들어 commit 한다.
Changeset action 이 version update PR 을 생성한다.
Version Update PR 을 Repository Owner 가 수동으로 승인한다.
CHANGELOG.md 와 package.json 의 변화를 감지해 GitHub Release 를 생성하고, npm 에 publish 한 뒤, API Document 를 업데이트 하고 GitHub Pages 에 Deploy 한다.

이는 배포에 대한 의사 결정 단계를 상정하여 Repository Owner 의 PR 수락 시점을 최종 배포 시점으로 설정한 프로세스이다. 이런 workflow 를 구현하기 위해 Changeset action 에 포함된 npm publish 단계를 생략하고, PR 수락 이후 npm publish 를 진행하도록 구성했다.

changesets.yml

1name: Changesets
2
3on:
4  push:
5    branches:
6      - main
7
8env:
9  CI: true
10  HUSKY: 0 # Disable husky hit hooks
11
12jobs:
13  version:
14    timeout-minutes: 15
15    runs-on: ubuntu-latest
16    permissions:
17      contents: write
18      pull-requests: write
19    outputs:
20      has_changes: ${{ steps.changesets.outputs.hasChangesets }}
21      pr_number: ${{ steps.changesets.outputs.pullRequestNumber }}
22    steps:
23      - name: Checkout code repository
24        uses: actions/checkout@v4
25        with:
26          fetch-depth: 0
27      
28      # This project uses pnpm as a package manager.
29      - name: Setup pnpm
30        uses: pnpm/action-setup@v4
31      
32      - name: Setup node.js
33        uses: actions/setup-node@v4
34        with:
35          node-version: 22
36          cache: 'pnpm'
37
38      - name: Install dependencies
39        run: pnpm install
40      
41      - name: Disable Git hooks
42        run: |
43          git config --global user.name "github-actions[bot]"
44          git config --global user.email "github-actions[bot]@users.noreply.github.com"
45          
46          # Disable husky git hooks
47          mkdir -p /tmp/empty-hooks
48          git config --global core.hooksPath /tmp/empty-hooks
49      
50      - name: Create and publish versions
51        id: changesets
52        uses: changesets/action@v1
53        with:
54          commit: "Release version update"
55          title: "Release version update"
56          # You can publish to npm here
57          publish: "pnpm build"
58        env:
59          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
60          # NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # required for npm publish
61          HUSKY: 0
62      
63      - name: Generate documentation for PR
64        if: steps.changesets.outputs.hasChangesets == 'true'
65        run: |
66          echo "Changesets created a PR #${{ steps.changesets.outputs.pullRequestNumber }}"
67          
68          # Get the branch name that changesets created
69          CHANGESET_BRANCH=$(gh pr view ${{ steps.changesets.outputs.pullRequestNumber }} --json headRefName -q .headRefName)
70          echo "Changesets branch: $CHANGESET_BRANCH"
71          
72          # Checkout that branch
73          git fetch origin $CHANGESET_BRANCH
74          git checkout $CHANGESET_BRANCH
75          
76          # Generate documentation
77          pnpm typedoc
78
79          # Verify docs were generated properly
80          if [ ! -f "./docs/index.html" ]; then
81            echo "Documentation generation failed!"
82            exit 1
83          fi
84          
85          # Commit and push the documentation changes
86          git add docs/
87          git commit -m "docs: Update documentation for release" || echo "No documentation changes to commit"
88          git push origin $CHANGESET_BRANCH
89        env:
90          GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}
91

Changeset action 으로 생성한 PR 에 Documentation 변경점을 commit 하는 과정을 추가했다. GitHub Pages Deployment 에는 영향을 주지 않지만, 해당 페이지에 표시되는 정보와 local 소스의 docs 디렉토리 하위 정보를 동기화하는 역할이다.

release-and-publish.yml

1name: Release and Publish
2
3on:
4  push:
5    branches:
6      - main
7    paths:
8      - 'CHANGELOG.md'
9      - 'package.json'
10  workflow_dispatch:
11
12jobs:
13  release-and-publish:
14    runs-on: ubuntu-latest
15    if: contains(github.event.head_commit.message, 'Release version update')
16    permissions:
17      contents: write
18      id-token: write
19    steps:
20      - name: Checkout code repository
21        uses: actions/checkout@v4
22        with:
23          fetch-depth: 0
24          
25      - name: Setup pnpm
26        uses: pnpm/action-setup@v4
27      
28      - name: Setup node.js
29        uses: actions/setup-node@v4
30        with:
31          node-version: 22
32          registry-url: 'https://registry.npmjs.org'
33          
34      - name: Install dependencies
35        run: pnpm install
36      
37      - name: Get package version
38        id: package-version
39        run: |
40          PACKAGE_VERSION=$(node -p "require('./package.json').version")
41          echo "version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
42      
43      - name: Get latest changes from CHANGELOG
44        id: changelog
45        run: |
46          # Extract the changes for the latest version
47          LATEST_CHANGES=$(sed -n "/## ${{ steps.package-version.outputs.version }}/,/## [0-9]/p" CHANGELOG.md | sed '$d' | sed '1d')
48          # Store the changes in a file to preserve newlines
49          echo "$LATEST_CHANGES" > latest_changes.txt
50          echo "changes_file=latest_changes.txt" >> $GITHUB_OUTPUT
51      
52      - name: Create GitHub Release
53        uses: softprops/action-gh-release@v2
54        with:
55          tag_name: v${{ steps.package-version.outputs.version }}
56          name: Release v${{ steps.package-version.outputs.version }}
57          body_path: ${{ steps.changelog.outputs.changes_file }}
58          draft: false
59          prerelease: false
60          generate_release_notes: true
61        env:
62          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
63      
64      - name: Build package for publishing
65        run: pnpm build
66      
67      - name: Publish to NPM registry
68        run: pnpm publish --no-git-checks
69        env:
70          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
71          HUSKY: 0
72
73  deploy:
74    permissions:
75      contents: read
76      pages: write
77      id-token: write
78    concurrency:
79      group: "pages"
80      cancel-in-progress: false
81    needs: release-and-publish
82    environment:
83      name: github-pages
84      url: ${{ steps.deployment.outputs.page_url }}
85    runs-on: ubuntu-latest
86    steps:
87      - name: Checkout
88        uses: actions/checkout@v4
89      - name: Setup Node.js
90        uses: actions/setup-node@v4
91        with:
92          node-version: 22
93      - name: Setup pnpm
94        uses: pnpm/action-setup@v4
95      - name: Install dependencies
96        run: pnpm install
97      - name: Generate documentation
98        run: pnpm typedoc
99      - name: Setup Pages
100        uses: actions/configure-pages@v5
101      - name: Upload artifact
102        uses: actions/upload-pages-artifact@v3
103        with:
104          path: './docs/'
105      - name: Deploy to GitHub Pages
106        id: deployment
107        uses: actions/deploy-pages@v4
108

CHANGELOG.md 와 package.json 이 변경됐을 때, 최근 commit message 가 "Release version update" 라면 두 가지 job 이 실행된다.

CHANGELOG.md 에 반영된 이번 업데이트 버전에 대한 변경 사항을 포함한 GitHub Release 를 생성하고, npm publish 를 진행한다.
앞선 job 이 성공하면, API Documentation 을 최신화하고 GitHub Pages 에 deploy 한다.

NOTE: 이 프로젝트는 husky 와 commitlint 로 commit 메시지의 형식을 제한하고 있어 "Release version update" 라는 메시지가 겹칠 일이 없지만, 같은 환경이 아니라면 조건 설정에 유의해야 한다.

Closing

npm 패키지를 사용만 해보고 직접 올려본 것은 처음인데, 실무를 겪어보면서 생긴 개발 업무 프로세스에 대한 개인적인 convention 을 잘 정리해서 반영하지 않았나 싶다. Branch naming convention, branch protection rules 등 협업을 고려한 프로세스도 기회가 되면 설계해보고 싶다.

Opening

Package Metadata

package.json

1{
2  "name": "@(scope)/(package-name)",
3  "version": "0.0.2",
4  "description": "package description",
5  "keywords": [],
6  "repository": {
7    "type": "git",
8    "url": "(github path)"
9  },
10  "homepage": "(homepage path)",
11  "bugs": {
12    "url": "(bug/issues report page path)"
13  },
14  "license": "MIT",
15  "author": {
16    "name": "(author name)",
17    "url": "(author homepage path)"
18  },
19  "peerDependencies": {
20    "cesium": "^1"
21  },
22}

필수로 명시해야 하는 것은 다음 두 가지가 있다.

name: 패키지의 이름으로, npm 에 publish 하기 위해서는 사용할 npm 계정에 publish 권한이 있는 scope 를 지정해주어야 한다. 개인 계정의 경우, username 과 같은 scope 는 기본으로 권한이 주어진다.
version: npm 은 semver 모듈로 패키지의 버전을 판단하기 때문에 형식을 맞춰주어야 한다. 이는 Semantic Versioning 규칙을 따르는 것으로, 이 프로젝트에서는 후술할 Changesets versioning 툴을 사용했다.

Project Configurations

TypeScript - Builds

기본 컴파일러인 tsc 를 사용해도 되지만, tsup 이라는 번들러를 이용했다. (그냥)

tsup.config.js

1import { defineConfig } from 'tsup';
2
3export default defineConfig({
4  clean: true,
5  dts: true,
6  entry: ['src/index.ts'],
7  esbuildOptions(options) {
8    options.platform = 'neutral';
9  },
10  format: ['cjs', 'esm'],
11  minify: true,
12  outExtension({ format }) {
13    return {
14      js: format === 'cjs' ? '.cjs' : '.js',
15    };
16  },
17  sourcemap: false,
18});
19

package.json

1{
2// ...
3  "type": "module",
4  "main": "dist/index.js",
5  "module": "dist/index.js",
6  "files": [
7    "dist"
8  ],
9  "types": "dist/index.d.ts",
10  "exports": {
11    ".": {
12      "types": "./dist/index.d.ts",
13      "import": "./dist/index.js",
14      "require": "./dist/index.cjs",
15      "default": "./dist/index.js"
16    }
17  },
18// ...
19}

type: 패키지 내에서 JavaScript 의 기본 확장자인 .js 를 어떻게 취급할지를 명시한다. module 이면 esm, common 이면 common js 로 취급한다.
main: 패키지의 기본 primary entry point.
module: 패키지를 esm 방식으로 접근할 때의 primary entry point.
files: 패키지가 포함하는 파일들로, .gitignore 의 반대격.
types: 패키지에 대한 type 을 추론할 수 있는 declaration (dts) 파일.
exports: main 에서 명시한 entry point 를 상세하게 나눠 명시하는 항목으로, require(Common JS) 로 접근하면 .cjs 파일을 참고하게 하는 것 등이 가능.

TypeScript - Documentation

JavaScript 는 JSDoc 이라는 documentation 양식이 있다. TypeScript 에서도 동일한 양식을 사용한다.

tsdoc.ts

1// TypeScript Documentation Example
2/**
3 * Abstract class that enhances Cesium collection objects with tagging functionality.
4 * This class provides a consistent API for working with different types of Cesium collections
5 * and allows grouping and manipulating collection items by custom tags.
6 *
7 * @abstract
8 * @template C - The type of Cesium collection (e.g., EntityCollection, PrimitiveCollection)
9 * @template I - The type of items in the collection (e.g., Entity, Primitive)
10 * @example
11 * ...
12 */
13abstract class Collection<C, I>{
14  ...
15}

typedoc.json

1{
2  "$schema": "https://typedoc.org/schema.json",
3  "entryPoints": ["src/index.ts"],
4  "out": "docs",
5  "name": "Name of this document",
6  "includeVersion": true,
7  "excludePrivate": false,
8  "excludeProtected": false,
9  "excludeExternals": true,
10  "readme": "README.md",
11  "githubPages": true,
12  "categorizeByGroup": true,
13  "navigationLinks": {
14    "GitHub": "Link to your project",
15    "NPM": "Link to your package"
16  }
17}

Versioning - Changesets

npm publish 는 package.json 의 name 과 version 이 primary key 로 작용한다. 같은 패키지 이름으로 이미 존재하는 버전으로는 다시 publish 할 수 없다.
Changeset 은 Changeset Actions 를 통해 CHANGELOG.md 의 내용을 수정할 수 있는데, Changeset 의 타입(patch/minor/major) 에 따라 package.json 의 version 을 함께 업데이트 하는 Pull Request 를 생성하도록 설정할 수 있다.
typedoc 으로 생성한 API Documentation 에는 패키지의 version 을 표시할 수 있는데, 이는 TypeDoc 실행 시점의 package.json version 을 기준으로 한다.

이런 점들을 고려해서 배포 과정을 자동화하되, 다음과 같은 배포 process 를 설계했다.

코드의 수정과 함께 주요 변경점을 담은 changeset 을 만들어 commit 한다.
Changeset action 이 version update PR 을 생성한다.
Version Update PR 을 Repository Owner 가 수동으로 승인한다.
CHANGELOG.md 와 package.json 의 변화를 감지해 GitHub Release 를 생성하고, npm 에 publish 한 뒤, API Document 를 업데이트 하고 GitHub Pages 에 Deploy 한다.

changesets.yml

1name: Changesets
2
3on:
4  push:
5    branches:
6      - main
7
8env:
9  CI: true
10  HUSKY: 0 # Disable husky hit hooks
11
12jobs:
13  version:
14    timeout-minutes: 15
15    runs-on: ubuntu-latest
16    permissions:
17      contents: write
18      pull-requests: write
19    outputs:
20      has_changes: ${{ steps.changesets.outputs.hasChangesets }}
21      pr_number: ${{ steps.changesets.outputs.pullRequestNumber }}
22    steps:
23      - name: Checkout code repository
24        uses: actions/checkout@v4
25        with:
26          fetch-depth: 0
27      
28      # This project uses pnpm as a package manager.
29      - name: Setup pnpm
30        uses: pnpm/action-setup@v4
31      
32      - name: Setup node.js
33        uses: actions/setup-node@v4
34        with:
35          node-version: 22
36          cache: 'pnpm'
37
38      - name: Install dependencies
39        run: pnpm install
40      
41      - name: Disable Git hooks
42        run: |
43          git config --global user.name "github-actions[bot]"
44          git config --global user.email "github-actions[bot]@users.noreply.github.com"
45          
46          # Disable husky git hooks
47          mkdir -p /tmp/empty-hooks
48          git config --global core.hooksPath /tmp/empty-hooks
49      
50      - name: Create and publish versions
51        id: changesets
52        uses: changesets/action@v1
53        with:
54          commit: "Release version update"
55          title: "Release version update"
56          # You can publish to npm here
57          publish: "pnpm build"
58        env:
59          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
60          # NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # required for npm publish
61          HUSKY: 0
62      
63      - name: Generate documentation for PR
64        if: steps.changesets.outputs.hasChangesets == 'true'
65        run: |
66          echo "Changesets created a PR #${{ steps.changesets.outputs.pullRequestNumber }}"
67          
68          # Get the branch name that changesets created
69          CHANGESET_BRANCH=$(gh pr view ${{ steps.changesets.outputs.pullRequestNumber }} --json headRefName -q .headRefName)
70          echo "Changesets branch: $CHANGESET_BRANCH"
71          
72          # Checkout that branch
73          git fetch origin $CHANGESET_BRANCH
74          git checkout $CHANGESET_BRANCH
75          
76          # Generate documentation
77          pnpm typedoc
78
79          # Verify docs were generated properly
80          if [ ! -f "./docs/index.html" ]; then
81            echo "Documentation generation failed!"
82            exit 1
83          fi
84          
85          # Commit and push the documentation changes
86          git add docs/
87          git commit -m "docs: Update documentation for release" || echo "No documentation changes to commit"
88          git push origin $CHANGESET_BRANCH
89        env:
90          GITHUB_TOKEN:${{ secrets.GITHUB_TOKEN }}
91

release-and-publish.yml

1name: Release and Publish
2
3on:
4  push:
5    branches:
6      - main
7    paths:
8      - 'CHANGELOG.md'
9      - 'package.json'
10  workflow_dispatch:
11
12jobs:
13  release-and-publish:
14    runs-on: ubuntu-latest
15    if: contains(github.event.head_commit.message, 'Release version update')
16    permissions:
17      contents: write
18      id-token: write
19    steps:
20      - name: Checkout code repository
21        uses: actions/checkout@v4
22        with:
23          fetch-depth: 0
24          
25      - name: Setup pnpm
26        uses: pnpm/action-setup@v4
27      
28      - name: Setup node.js
29        uses: actions/setup-node@v4
30        with:
31          node-version: 22
32          registry-url: 'https://registry.npmjs.org'
33          
34      - name: Install dependencies
35        run: pnpm install
36      
37      - name: Get package version
38        id: package-version
39        run: |
40          PACKAGE_VERSION=$(node -p "require('./package.json').version")
41          echo "version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
42      
43      - name: Get latest changes from CHANGELOG
44        id: changelog
45        run: |
46          # Extract the changes for the latest version
47          LATEST_CHANGES=$(sed -n "/## ${{ steps.package-version.outputs.version }}/,/## [0-9]/p" CHANGELOG.md | sed '$d' | sed '1d')
48          # Store the changes in a file to preserve newlines
49          echo "$LATEST_CHANGES" > latest_changes.txt
50          echo "changes_file=latest_changes.txt" >> $GITHUB_OUTPUT
51      
52      - name: Create GitHub Release
53        uses: softprops/action-gh-release@v2
54        with:
55          tag_name: v${{ steps.package-version.outputs.version }}
56          name: Release v${{ steps.package-version.outputs.version }}
57          body_path: ${{ steps.changelog.outputs.changes_file }}
58          draft: false
59          prerelease: false
60          generate_release_notes: true
61        env:
62          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
63      
64      - name: Build package for publishing
65        run: pnpm build
66      
67      - name: Publish to NPM registry
68        run: pnpm publish --no-git-checks
69        env:
70          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
71          HUSKY: 0
72
73  deploy:
74    permissions:
75      contents: read
76      pages: write
77      id-token: write
78    concurrency:
79      group: "pages"
80      cancel-in-progress: false
81    needs: release-and-publish
82    environment:
83      name: github-pages
84      url: ${{ steps.deployment.outputs.page_url }}
85    runs-on: ubuntu-latest
86    steps:
87      - name: Checkout
88        uses: actions/checkout@v4
89      - name: Setup Node.js
90        uses: actions/setup-node@v4
91        with:
92          node-version: 22
93      - name: Setup pnpm
94        uses: pnpm/action-setup@v4
95      - name: Install dependencies
96        run: pnpm install
97      - name: Generate documentation
98        run: pnpm typedoc
99      - name: Setup Pages
100        uses: actions/configure-pages@v5
101      - name: Upload artifact
102        uses: actions/upload-pages-artifact@v3
103        with:
104          path: './docs/'
105      - name: Deploy to GitHub Pages
106        id: deployment
107        uses: actions/deploy-pages@v4
108

CHANGELOG.md 와 package.json 이 변경됐을 때, 최근 commit message 가 "Release version update" 라면 두 가지 job 이 실행된다.

CHANGELOG.md 에 반영된 이번 업데이트 버전에 대한 변경 사항을 포함한 GitHub Release 를 생성하고, npm publish 를 진행한다.
앞선 job 이 성공하면, API Documentation 을 최신화하고 GitHub Pages 에 deploy 한다.