리액트 | 리액트 프로젝트 GitHub page로 배포하기

이번 글에서는 리액트로 만든 프로젝트를 GitHub page로 배포하는 방법에 대해 정리해보고자 한다. GitHub page라고 한다면 https://{user_name}.github.io와 같은 주소를 사용하는 GitHub을 통해 배포하는 개인 홈페이지, 일종의 블로그를 의미한다. (모든 것을 직접 만들어야하니 블로그보다는 홈페이지에 가깝다고 할 수 있다. 다만 이를 GitHub 블로그로 사용하는 사용자들이 많을 뿐...)

---

해당 프로젝트는 npx create-react-app 커맨드를 이용하여 생성된 프로젝트이다. 그럼 바로 알아보러 가자.

 

GitHub Page로 리액트 프로젝트 배포하기

GitHub repository 생성

먼저 해당 프로젝트가 GitHub에 업로드되어 있지 않는다면, 해당 프로젝트가 위치할 repository를 하나 만들어준다. 모든 코드를 GitHub에 업로드할 필요는 없으니, 모든 코드를 업로드하기 싫어도 배포를 위해서 비어있는 repository를 만들어준다. 이 repository에는 배포를 하기 위한 코드가 올라갈 것이다. 만약 모든 코드를 이미 GitHub에 업로드하고 있었다면, 그 repository를 그냥 그대로 사용하면 된다.

(여기서 repository를 생성하는 자세한 방법을 다루지는 않는다.)

 

gh-pages 패키지 설치

gh-pages라는 패키지를 리액트 프로젝트에 설치한다. 프로젝트 위치에서 npm i gh-pages 커맨드를 실행한다.

npm i gh-pages

gh-pages 패키지는 리액트로 만든 결과물을 GitHub Page에 업로드하는 것을 도와주는 패키지이다.

 

package.json 설정

package.json 파일 맨 마지막에 해당 프로젝트의 주소(가장 메인이 되는 주소)를 입력한다. 주소의 형식은 아래와 같다.

"homepage": "https://{user_name}.github.io/{repository_name}"

해당 프로젝트의 GitHub repository 이름이 기억나지 않는다면, git remote -v 명령어를 통해 확인하거나 직접 GitHub으로 이동하여 repository 이름을 확인하면 된다. user_name은 본인의 GitHub 이름을 입력하면 된다.

만약 본인의 GitHub 이름이 luna이고, 해당 프로젝트가 위치할 repository 이름이 my-app이라면, "homepage": "https://luna.github.io/my-app"을 package.json 파일의 마지막 부분에 추가해주면 된다.

package.json 설정 예시

 

주소 설정이 끝났으면, package.json 파일에 아래 두 개의 스크립를 추가해야 한다. 두 script는 package.json 파일의 scripts 부분에 추가하면 된다. 

"deploy": "gh-pages -d build"
"predeploy": "npm run build"

package.json의 scripts 예시

deploy는 앞에서 설치한 gh-pages 패키지를 실행하며, predeploy는 deploy를 실행하면 먼저 실행되는 스크립트이다. 만약 predeploy를 추가하지 않으면, 해당 프로젝트를 업로드할 때, npm run build를 실행한 후, npm run deploy를 실행해야 한다. 하지만 predeploy를 추가하면 npm run deploy만 실행해도 자동으로 먼저 npm run build가 실행되고 이후 deploy 스크립트가 실행되게 된다.

 

프로젝트 배포하기

위 설정까지 완료되었으면, 이제 프로젝트를 배포할 차례이다. 터미널에 npm run deploy를 실행하면 된다. 프로젝트 폴더에는 build 폴더가 추가된 것을 확인할 수 있다.

npm run deploy 실행 결과

이후 GitHub으로 이동해서 repository를 확인하면 기존에 프로젝를 업로드한 사람은 main branch 이외에 gh-pages라는 branch가 생성된 것을 확인할 수 있고, 단순히 배포용도로만 repository를 사용하는 사람은 gh-pages라는 branch만 있는 것을 확인할 수 있다.

GitHub repository의 Settings - Pages로 이동하면 Branch 항목에 gh-pages가 선택되어 있는 것을 볼 수 있다. 만약 gh-pages가 아니라 다른 branch로 설정되어 있다면 gh-pages로 설정한 후 저장한다.

여기까지 완료가 되었으면, 배포는 끝이다. 배포까지는 약 5분 정도의 시간이 소요되며, 이후 위에서 입력했던 주소로 이동하면 업로드한 프로젝트의 페이지가 정상적으로 배포되고 있는 것을 확인할 수 있다.

---

흰 바탕의 페이지만 나오는 경우

실제로 배포를 진행해보니, 페이지가 로드되지 않고 흰색 바탕의 페이지만 나오는 오류를 발견하였다. 찾아보니 해당 문제는 react-router-dom 6버전 이상을 사용하는 사용자에게만 발생하는 것 같았다.

(필자가 현 시점에서 사용하고 있는 react-router-dom의 버전은 6.21.2이다.)

 

해결 방법은 Router 컴포넌트에 basename 속성을 추가하는 것이다. 아래와 같이 Router 컴포넌트에 basename={process.env.PUBLIC_URL}을 추가한다.

...
    <Router basename={process.env.PUBLIC_URL}>
      <Routes>
        <Route path="/" element={<Home />} />
        ...
      </Routes>
    </Router>
...

그럼 정상적으로 페이지가 출력되는 결과를 확인할 수 있다.