[React] GitHub Pages 배포 및 Router 오류 해결 방법

안녕하세요, hr0513입니다! 🥰

오늘은 React 앱을 GitHub Pages에 배포하고,

배포 후 발생할 수 있는 Router 오류를 해결하는 방법에 대해 정리해 보겠습니다.

---

1. React 앱 설치

먼저, React 앱을 생성합니다.

아래 명령어로 새로운 React 프로젝트를 시작해 보세요.

yarn create react-app (프로젝트명)

 

2. 필요한 라이브러리 설치

프로젝트에 필요한 라이브러리를 설치합니다.

주로 사용하는 react-router-dom, react-query, styled-components, react-icons, sass 등을 설치합니다.

yarn add react-router-dom react-query styled-components react-icons sass

 

3. 프로젝트 빌드

3-1. 빌드 실행

앱을 GitHub Pages에 배포하려면 빌드를 해야 합니다.

아래 명령어로 빌드합니다.

yarn build

 

3-2. GitHub Pages 활성화

GitHub 저장소의 Settings > Pages에서 Branch를 master로 설정 후 Save 합니다.

3분 정도 기다리면, Visit site 버튼이 활성화됩니다.

이 버튼을 클릭하여 사이트를 확인하고, 아래 링크 형식으로 프로젝트 URL을 복사합니다:

---

4. GitHub Pages 배포 설정

4-1. package.json 설정

GitHub Pages에 배포하기 위해 몇 가지 설정을 추가해야 합니다.

package.json 파일을 열어 다음과 같이 설정을 추가합니다.

 

ps. 복사한 프로젝트 URL을 homepage 값에 넣습니다.

"homepage": "https://(본인 깃허브명).github.io/(프로젝트명)/", // 추가
"scripts": {
	...
    "build": "react-scripts build",
    "deploy": "gh-pages -d build" // 추가
  },

 

4-2. 빌드 시키기

위 설정을 마친 후, 다시 한번 빌드를 실행합니다.

yarn build

 

4-3. gh-pages 설치

아래 명령어로 gh-pages 패키지를 설치해 주세요.

yarn add gh-pages --dev

 

4-4. commit & push 진행

커밋 & 푸쉬를 진행해 주세요.

---

5. GitHub Pages에 배포

5-1. 배포 명령어 실행

배포 명령어를 실행합니다.

yarn deploy

 

5-2. 배포 GitHub 설정

배포가 완료되면, Settings > Code and automation > Pages에서 Branch를 gh-pages로 설정 후 Save 합니다.

이후 GitHub Pages에서 제공하는 'Visit site' 버튼을 통해 배포된 사이트를 확인할 수 있습니다.

약 3분 정도 기다리면 사이트가 활성화됩니다.

---

6. Router 오류 해결

GitHub Pages에 배포하고 나면, 라우팅 관련 오류가 발생할 수 있습니다. (ex. 화면에 보이지 않음)

HashRouter로 감싸주면 GitHub Pages에서 발생하는 라우터 오류를 해결할 수 있습니다.

예시는 아래와 같습니다:

import { HashRouter, Route, Routes } from "react-router-dom";

const App = () => {
  return (
    <HashRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </HashRouter>
  );
};

---

6. 결과 화면

위 과정을 거치면 아래처럼 배포된 React 앱을 GitHub Pages에서 확인할 수 있습니다.

---

React 배포하시는 분들께 도움이 되었으면 좋겠어요!