Viteを使って制作したReactアプリをGithub Pagesにデプロイする

この記事はプログラミング学習者がアプリ開発中に躓いた内容を備忘録として記事におこしたものです。内容に不備などあればご指摘頂けると助かります。

学習の成果物としてViteを使ったReactアプリを制作、Github Pagesへデプロイする機会がありましたので、記事にまとめております。

1, デプロイしたいアプリを制作する

npm create vite@latestをターミナルで実行してViteを使った開発環境を整えていきます。

1, Project name 開発環境を整える際のディレクトリ名となります。
2, Select a framework 使用するフレームワークを指定 (※画面ではReactを指定)
3, Select a variant (使用する開発環境を決めるような意味合い。一般的にはSWCが高速なので推奨)

上記の内容を決定したら次のコマンドを実行して開発に必要なデータをインストールします。
cd 新しく生成されたプロジェクトのディレクトリ 生成したディレクトリに移動
npm install
npm run dev
これで初期データによる開発環境でのアプリ起動が実現できます。
npm run devを実行したらターミナルで下記のようなローカルのデプロイ先を教えてくれるので、そこにアクセスしましょう。
http://localhost:5173
※この内容はお使いの開発環境によってポート番号などが変わるので、正しいデプロイ先はターミナルに表示される内容を参照してください。

この後は必要な実装を行い、アプリを完成させましょう！

以下はアプリが完成してデプロイする際の内容となります。

※勿論、アプリ完成前に実装しても問題ありません。

2, vite.config.jsの設定

生成されたvite.config.jsを開いてどのディレクトリからホスティングするのかを追記します。
そのためにはbaseという項目を新しく追記して、そこにリモートリポジトリの名前を記述します。
/react_todo_list2/のようにリポジトリ名の前後を必ずスラッシュで囲んでください。
これにより記入したリモートリポジトリから制作したアプリをデプロイするという指示になります。
また、後述するbuild時の生成ファイル(dist)について、保存先を指定することもできます。
build: outDirの部分でbuild時に生成されるdistファイルの出力先を変更できます。
下のスクショではdocsディレクトリに指定しています。

3, package.jsonの設定

生成されたpackage.jsonにGithub Pagesで使用されるURLを記載します。
hompeageという項目は無いので、新しく自分で追記する必要があります。
https://<ユーザー名>.github.io/<リポジトリ名>/という記述方法になります。
※先にGithub Pagesの設定を済ませて、URLをコピーしてきても良いかと思います。

4, npm run buildの実行

ホスティングに使うビルドファイルを生成するためにnpm run buildを実行します。
場所はvite.config.jsとpackage.jsonのある場所で実行します。
もし違う場所で実行するとエラーで怒られるのでご注意ください。

下のスクショはnpm run buildを実行した時の画像です。
保存先がdocsになっている点にご注意ください。
これはvite.config.jsの設定でdocsを指定しているためです。
この指定がない場合、distというディレクトリの中にビルドファイルが生成されます。

初期状態ではdistは.gitignoreから外さないとgitで管理できないのでご注意ください。
下のスクショではdist部分をコメントアウトしています。
distファイル(index.htmlとcssとjsファイル)の保存先や名前を指定したい時はvite.config.jsの設定でbuild指定を行ってください。

5, Github Pagesの設定

最後にGithub Pagesでデプロイするリポジトリでの設定を行います。
※以下の数字は下のスクショ上の番号と連動しています。

①Githubで該当のリポジトリの画面に遷移してSettingsをクリック
②左側のサイドメニューでPagesをクリック
③Deploy from a branch か Github Actionsを選択
※ここではDeploy from a branchの設定となります。
④実際にどのブランチのどのディレクトリ{/(ルート) or docs}からデプロイするか設定します。
※1 ここではreact-todoブランチのdocsディレクトリからデプロイする設定です。
※2 指定しているディレクトリ(ここではdocs)の中にnpm run buildで生成されたビルドファイルが入っている必要があります。
⑤設定が終わると少し時間が掛かりますが、デプロイ先のURLが表示されます。

6, 失敗談

README.mdしか表示されない事例

実装当初は以下のようなディレクトリ構成でした。

  ├─ README.md
  └─ docs/ (Github Pagesはこの中にビルドファイルがある前提で動いてしまう)
      ├─ package.json
      ├─ vite.config.js
      ├─ src/
      ├─ docs(npm run buildで生成したビルドファイル)
      └─ ... その他

この時、Github Pagesの設定で対象リポジトリのdocsディレクトリからのデプロイ設定だったので、GithubにPushした後にGithub PagesのURLにアクセスすると最初は真っ白。
そして、再読み込みするとREADME.mdの内容が反映される状態でした。
恐らくdocsディレクトリを見てもビルドファイルが見つからないので、mdを反映したのでしょうか。
誤りに気付いてからは下記の構成に変更しました。

/（ルート）
  ├─ README.md
  ├─ package.json
  ├─ vite.config.js
  ├─ src/（Reactなどのソース）
  ├─ docs/（←ビルド成果物。GitHub Pagesの公開ディレクトリに指定）

これで何とかGithub Pagesへのデプロイを完了することができました。

npm run buildに失敗した事例

私の失敗談としてnpm create vite@latestを実行した時にプロジェクト名(=ディレクトリ名)をdocsにしてしまったミスがあります。
このミスの理由ですが、npm create vite@latestで生成したファイル類でデプロイされると思っていたので、初めからそこをdocsにしておけばGithub Pagesにデプロイする時もスムーズにいくと踏んでいたからです。今から考えるとGithub Pagesのデプロイするディレクトリを/(ルート)にすればわざわざdocsに指定する必要も無いわけですが。
ですが、実際にデプロイで使用されるファイル類はnpm run buildで生成されたファイル類になるわけです。また、ルートディレクトリをdocsにして、且つnpm run buildで生成されるディレクトリもdocsに指定している場合、npm run buildはエラーで阻まれて実行できませんでした。理由は簡単でルートディレクトリ直下には開発用で使っていたindex.htmlなどのファイルがあります。npm run buildで生成されたビルド用ファイルと名前が同一の場合は上書きされる危険があるので、エラーで知らせてくれました。
以下はエラー文の抜粋です。
(!) build.outDir must not be the same directory of root or a parent directory of root as this could cause Vite to overwriting source files with build outputs.
このエラーに遭遇した後はルートディレクトリをdocsから別名に変更し、また、vite.config.jsとpackage.jsonをルートディレクトリ直下に移動してもう一度npm run buildを実行することで、やっとGithub Pagesへデプロイできました。

参考にした記事など

How To Deploy A React Vite App to Github Pages (Simple)
【備忘録】Git - push時のエラーの解消
【今更】Gitのバッファサイズを変更する
Getting Started - Vite