GitHub Pages에 리액트 프로젝트(React + Vite) 배포하기

이번 블로그 글에서는 GitHub Pages를 사용해 특정 폴더 안에 있는 리액트 프로젝트를 배포하는 방법에 대해 다룹니다. 배포한 프로젝트는 https://username.github.io/repository-name/ 형식으로 접근할 수 있게 됩니다. 저는 레포지토리 안의 디렉토리에 배포 파일이 존재하기 때문에, 아래와 같은 URL로 접근할 수 있도록 설정했습니다.

https://an0401na.github.io/React_Study/08-Refs-Portals/

Refs & Portals

제가 위와 같이 설계했던 이유는 리액트 강의를 들으며 만들었던 페이지를 같은 레포지토리의 다른 디렉토리로 구분하여 배포할 예정이 있기 때문입니다.

React_Study/            # 레포지토리 이름
 ├── 08-Refs-Portals/   # 첫 번째 배포된 리액트 페이지
 │    └── dist/         # 빌드된 파일
 ├── 09-AnotherPage/    # 두 번째 배포될 리액트 페이지
 │    └── dist/         # 빌드된 파일
 ├── 10-AnotherExample/ # 세 번째 배포될 리액트 페이지
 │    └── dist/         # 빌드된 파일
 └── ...                # 추가적인 배포될 페이지들

위와 같은 구조로 각 페이지마다 별도의 디렉토리를 두고, 각 디렉토리마다 dist 폴더에 빌드 파일을 생성하여 배포합니다. 각 페이지는 https://username.github.io/React_Study/08-Refs-Portals/, https://username.github.io/React_Study/09-AnotherPage/와 같은 URL로 접근할 수 있게 됩니다.

 

1. GitHub 블로그 만들기

GitHub에서 프로젝트를 배포하려면 먼저 GitHub Page를 활성화 하기 위해 깃허브 블로그를 생성해주어야 합니다.

New 버튼을 눌러 새로운 레포지토를 생성하는데 꼭 <본인계정명>.github.io로 생성해주세요.

2. 프로젝트 올릴 레포 만들기

배포할 리액트 프로젝트를 GitHub에 올릴 레포지토리를 생성합니다. 해당 레포지토리에는 main 브랜치에서 소스 코드가 관리되고, gh-pages 브랜치에는 배포 파일이 관리됩니다.

3. 레포지토리의 디렉토리 구조

프로젝트 구조는 아래와 같으며, 리액트 프로젝트의 소스 코드가 08-Refs-Portals 폴더 내에 위치한다고 가정합니다.

gh-pages 브랜치에서 목표로하는 디렉토리 구조는 아래와 같습니다.

React_Study/       # 레포지토리명 
 └── 08-Refs-Portals/ # 레포지토리 안의 폴더명
      └── dist/    # 빌드된 파일

4. 빌드 준비하기

1. 프로젝트 디렉토리에서 필요한 의존성을 설치합니다. (프로젝트 경로에서 실행)

PS C:\\workspace\\React_Study\\08-Refs-Portals> npm install

2.  gh-pages를 개발 의존성으로 설치합니다.

PS C:\\workspace\\React_Study\\08-Refs-Portals>  npm install --save-dev gh-pages

package.json 설정

homepage를 GitHub Pages URL로 설정합니다. 그리고 deploy 스크립트를 추가합니다.

  "homepage": "<https://an0401na.github.io/React_Study/08-Refs-Portals/>",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "deploy": "gh-pages -d dist"
  }

vite.config.js 설정

Vite의 base 경로를 설정하여 GitHub Pages에서 서브 폴더로 배포될 수 있도록 합니다.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/React_Study/08-Refs-Portals/'
})

5. 빌드 실행

PS C:\\workspace\\React_Study\\08-Refs-Portals> npm run build

이 명령어로 main 브랜치에서 dist 폴더에 빌드된 파일들이 생성됩니다.

6. 배포 파일 커밋

1. dist 폴더에 있는 파일들을 main 브랜치에 강제로 추가합니다.

PS C:\\workspace\\React_Study\\08-Refs-Portals> git add -f dist/*

주의: 소스 코드가 아닌 dist 디렉토리만 추가해야 합니다. 소스 코드와 함께 올라가면, GitHub Pages에서 index.html이 아닌 소스 코드가 보여질 수 있습니다.

2. main 브랜치로 커밋을 진행합니다.

PS C:\\workspace\\React_Study\\08-Refs-Portals>  git commit -m "Deploy updated build to gh-pages"

중요: 아직 PUSH는 하지마세요. gh-pages 브랜치에 푸시할 준비가 되지 않았으므로, 푸시 작업은 아직 하지 않습니다 build된 파일은 다른 브랜치(gh-pages)에 올릴테니까요.

 

7. Push

레포지토리 루트 디렉토리로 이동한 후, gh-pages 브랜치로 배포 파일을 푸시합니다.

PS C:\\workspace\\React_Study> git subtree push --prefix 08-Refs-Portals/dist origin gh-pages

만약 gh-pages 브랜치가 아직 생성되지 않았다면, 아래 명령어로 새로운 브랜치를 생성합니다.

PS C:\\workspace\\React_Study> git checkout --orphan gh-pages

8. GitHub Pages 설정

GitHub에서 프로젝트 페이지를 활성화하려면 Settings > Pages에서 배포할 브랜치로 gh-pages를 선택합니다.

• Source에서 gh-pages를 선택하고, Save 버튼을 클릭합니다.

9. 배포 완료

배포가 완료된 후, 아래 URL을 통해 프로젝트를 확인할 수 있습니다:

https://username.github.io/React_Study/08-Refs-Portals/