React で作った ToDo アプリを GitHub Pages で公開してみた

GitHub Pages で React + Vite の ToDo アプリを公開してみた

React + Vite + TypeScript で作った小さな ToDo アプリを、GitHub Pages で公開するまでの流れをまとめます。

今回の目的は、AI バイブコーディングで小さな Web アプリを一から作り、最後に公開まで持っていくことでした。

先に結論

GitHub Pages で React アプリを公開するなら、npm run build で生成した静的ファイルを配信する必要があります。

GitHub Pages は、単純にリポジトリのルートや docs/ を公開するだけだと、Vite の開発用ファイルや TypeScript のソースをそのまま動かせません。

そのため、今回は GitHub Actions を使って dist/ をデプロイしました。

作ったもの

最小構成の ToDo アプリです。

• ToDo を追加
• ToDo 一覧を表示
• ToDo を編集
• ToDo を削除
• 完了 / 未完了を切り替え
• localStorage に保存

バックエンドやデータベースは使っていません。

技術構成

• React
• TypeScript
• Vite
• CSS
• localStorage

できるだけシンプルにしたかったので、状態管理ライブラリや UI ライブラリは使いませんでした。

実装の考え方

ファイルはかなり少なくしました。

• UI は App.tsx
• ToDo の型は types.ts
• localStorage の読み書きは storage.ts

この分け方にしたのは、React を学び始めた段階でも流れを追いやすくするためです。

つまずいた点

1. dist/index.html を直接開いても白画面になった

最初はビルド後の dist/index.html をそのままブラウザで開いていました。

しかし、file:// で直接開くと、Vite が出力した JavaScript や CSS の読み込みがうまくいかず、白画面になることがありました。

そのため、ローカル確認は npm run preview を使うようにしました。

npm run preview

2. GitHub Pages で公開したら 404 や白画面になった

最初は GitHub Pages の設定が不十分で、公開 URL にアクセスしても 404 になりました。

また、開発用の index.html をそのまま配信してしまうと、/src/main.tsx を参照するので GitHub Pages では動きません。

React + Vite のアプリは、ソースそのものではなく dist/ を配信する必要があります。

GitHub Pages の基本

GitHub Pages は、設定によって公開元を決めます。

よくある方法は次の 2 つです。

• リポジトリのルートを公開する
• docs/ フォルダを公開する

ただ、React + Vite のようなフロントエンドアプリでは、ビルド結果をそのまま公開したいことが多いです。

そこで、GitHub Actions を使うと便利です。

GitHub Actions を使った方法

GitHub Actions でやったことは単純です。

1. npm ci
2. npm run build
3. dist/ を GitHub Pages にデプロイ

workflow はこんな感じです。

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

これで、dist/ 配下の CSS や JavaScript を相対パスで参照できるようになります。

うまく動くまでの流れ

実際には、次の順番で進みました。

1. React + Vite + TypeScript で ToDo アプリを作る
2. localStorage で保存する
3. npm run build でビルドできることを確認する
4. GitHub Pages で公開しようとして白画面や 404 に遭遇する
5. GitHub Actions で dist/ をデプロイする構成に変える
6. Settings > Pages で GitHub Actions を有効化する
7. 公開 URL で表示確認する

学び

今回の学びはかなりはっきりしています。

• React アプリはソースではなくビルド成果物を公開する
• GitHub Pages の設定だけでは足りない場合がある
• GitHub Actions を使うと公開手順を自動化できる
• 小さいアプリでも、公開までやると学びが増える

まとめ

React で作った ToDo アプリを GitHub Pages で公開するのは、思ったより簡単でした。

ただし、ローカル開発と本番公開では見ているファイルが違います。

ポイントは次の 2 つです。

• npm run build で dist/ を作る
• GitHub Actions で dist/ を Pages に配信する

小さいアプリでも、最後に公開までやると「動くものを外に出す」経験になりました。