GitHub Page에 간단한 React 웹 페이지를 만드는 방법

GitHub Page에 간단한 React 웹 페이지를 만드는 방법을 대해 설명한다.

GitHub Pages에 React 웹 페이지를 배포하는 가장 쉽고 무료인 방법은 Vite로 프로젝트를 만들고, gh-pages 패키지를 이용해 자동 배포하는 것이다.

다음 단계에 따라 간단한 React 웹 페이지를 만들어 배포해 보자.


1단계: React 프로젝트 생성 (Vite 사용)

Vite는 Create React App(CRA)보다 훨씬 빠르고 가볍게 React 환경을 구성할 수 있다. Node.js가 설치되어 있는 상태에서 터미널에 아래 명령어를 입력한다.

# 프로젝트 생성 (devkuma-react-app은 원하는 폴더명으로 변경 가능)
npm create vite@latest devkuma-react-app -- --template react

# 프로젝트 폴더로 이동
cd devkuma-react-app

# 필요한 패키지 설치
npm install

2단계: GitHub에 새 저장소(Repository) 만들기

  1. GitHub에 로그인한 뒤 우측 상단의 + 아이콘을 눌러 New repository를 선택한다.

  2. Repository name을 입력한다. (예: devkuma-react-app)

  3. Public(공개)으로 설정하고, 다른 옵션(README 등)은 체크하지 않은 채 Create repository를 누른다.

3단계: 프로젝트 설정 수정 (vite.config.js)

GitHub Pages는 보통 https://<사용자이름>.github.io/<저장소이름>/ 주소로 배포된다. 하위 경로를 올바르게 읽을 수 있도록 설정 파일을 수정해야 한다.

vite.config.js 파일을 열고 defineConfig 안에 base 속성을 추가해 주세요. (저장소 이름을 devkuma-react-app이라고 가정한다.)

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

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  base: '/devkuma-react-app/', // 본인의 GitHub 저장소 이름으로 변경하세요 (앞뒤로 슬래시 필수)
})

4단계: 배포 도구(gh-pages) 설치 및 설정

터미널에서 아래 명령어를 실행하여 GitHub Pages 배포를 도와주는 패키지를 설치한다.

npm install gh-pages --save-dev

이어서 package.json 파일을 열고 "scripts" 부분을 아래와 같이 수정한다. (homepage 줄도 추가해 준다.)

{
  "name": "devkuma-react-app",
  "private": true,
  "version": "0.0.0",
  "homepage": "https://<본인깃허브아이디>.github.io/devkuma-react-app",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  },
  ...
}
  • <본인깃허브아이디>와 저장소 이름 부분을 본인 정보에 맞게 수정한다.

5단계: GitHub 연동 및 배포 실행

로컬에서 작업한 코드를 깃허브에 연결하고 배포 명령어를 실행한다.

# 1. 깃 초기화 및 원격 저장소 연결
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/<본인깃허브아이디>/devkuma-react-app.git
git push -u origin main

# 2. GitHub Pages에 배포하기
npm run deploy

마지막에 npm run deploy 명령어가 정상적으로 실행되면 Published 메시지가 뜬다.

6단계: GitHub에서 Pages 설정 확인하기

  1. 본인의 GitHub 저장소 페이지로 이동한다.
  2. 상단 메뉴에서 Settings를 누른다.
  3. 좌측 사이드바에서 Pages를 클릭한다.
  4. Build and deployment 항목의 Branch가 gh-pages 브랜치로 설정되어 있는지 확인한다. (보통 자동으로 설정된다.)

잠시 후 페이지가 빌드되면 상단에 안내되는 URL(https://<본인아이디>.github.io/devkuma-react-app/)을 통해 배포된 React 웹 페이지를 확인할 수 있다.