React (Vite) アプリをGitHub Pagesに最短でデプロイする手順

はじめに

今回Reactアプリを実装しGitHub Pagesにデプロイしようとしたところ数々のエラーが出て思うように進まなかったので、デプロイする方法を簡単に再現できるように手順を記事にまとめることにしました。

1. 準備

• npm install gh-pages --save-dev でツールを入れる。
• package.jsonの"devDependencies"に"gh-pages"が表示されていればOK。

2. 設定ファイルの編集

• package.json: scripts に predeploy と deploy を追加。
• これにより、npm run deploy を叩くだけで「自動ビルド → gh-pages ブランチへのアップロード」が一気に走るようになります。

package.json

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

• vite.config.js: base: "/リポジトリ名/" を追加。
• これを忘れると、ブラウザが JS や CSS ファイルを見つけられず「真っ白」になります。

vite.config.js

export default defineConfig({
  base: "/react_trello_clone/",
  plugins: [react()],
});

3. デプロイ実行

• ターミナルで npm run deploy を実行。

terminal

npm run deploy

> trello_clone@0.0.0 predeploy
> npm run build


> trello_clone@0.0.0 build
> vite build

vite v7.3.1 building client environment for production...
✓ 84 modules transformed.
dist/index.html                       0.44 kB │ gzip:   0.27 kB
dist/assets/mountain2-C43ololf.jpg  231.12 kB
dist/assets/index-CN9_f_qD.css        1.54 kB │ gzip:   0.64 kB
dist/assets/index-DezeZ8i7.js       369.81 kB │ gzip: 114.77 kB
✓ built in 469ms

> trello_clone@0.0.0 deploy
> gh-pages -d dist

Published

• npm run deployを実行した瞬間にリポジトリにgh-pagesというブランチが自動で作成されます。

4. GitHub上の設定

• Settings > Pages で、Source が Deploy from a branch、Branch が gh-pages になっていることを確認。
• リンクに飛べばサイトを閲覧できるようになります。

真っ白になった場合の対処法

設定を全て設定し、その設定に間違いがないことを確認しても尚、表示されない場合は一旦distフォルダを削除し、再度build→deployをすることで反映されるかと思います。

# distファイルを削除
rm -rf dist
# デプロイ
npm run deploy

真っ白になる原因はこちら

今後の変更を反映する方法

これからは、アプリを更新して公開したくなったら、以下のコマンドを打つだけでOKです。

# 1. コードの変更を作業ブランチに保存
git add .
git commit -m "update: タスク追加機能の実装"
git push origin 対象ブランチ

# 2. 公開サイトを更新
npm run deploy