Deploying a React + Vite App to GitHub Pages using GitHub Actions

📝 Summary

In this tutorial, you are going to see how to:

1. Create a new React + Vite app.

2. Create a GitHub public repository.

3. Configure GitHub Actions Token Permissions.

4. Setup GitHub Actions workflow: Deploy React + Vite app to GitHub Pages.

5. Push the code to your GitHub repository.

6. Enable GitHub Pages sourced by gh-pages branch.

🧰 Step 1: Create a new React + Vite app

Run the following command to create a new React + Vite app:

npm create vite@latest app-name -- --template react

Replace the "app-name" with the name of your app/project

Vite has just created your app, let's navigate into the new app folder and run the command to install the dependencies:

cd app-name
npm install

Now you just have to wait the installation of the dependencies, and after that, to see your app running you need to run the command:

npm run dev

This will start the development server, and you should see an output like this:

  VITE vA.B.C  ready in X ms

  ➜  Local: http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Open your browser and head to http://localhost:5173 and you should see the default welcome page!

🔓 Step 2: Create a GitHub public repository

Go to your GitHub repositories page/tab:

In the top right of the page, click on the button "New"
Inform the "Repository name"
And keep it as a Public repository (Anyone on the internet can see this repository. You choose who can commit.)
Then, at the end of the page click on the button "Create repository"
And that is it. Your public repository is created!

🔐 Step 3: Configure GitHub Actions Token Permissions

Enable Write Permissions for the `GITHUB_TOKEN`

Settings > Actions > General
Scroll down untill the end of the page and in the Workflow permissions section select "Read and write permissions"
Optional: You can also check the "Allow GitHub Actions to create and approve pull requests" if needed
Click the Save button

🤖 Step 4: Setup GitHub Actions workflow: Deploy React + Vite app to GitHub Pages

In the root folder of your project:

Set the homepage (base path) at the beggining of the package.json file:

"homepage": "https://<your-username>.github.io/<your-repo-name>/"

For Vite, use base in the vite.config.js file.

export default defineConfig({
  ...
  base: '/<your-repo-name>/',
  ...
})

Create a new folder named .github in the root folder of the project
Inside the new .github folder, create a new folder named workflows
Inside the new workflows folder, create a new file named deploy.yml
Inside the new deploy.yml file, paste the following content:

name: Deploy React App with Vite to GitHub Pages

on:
  push:
    branches:
      - main  # or your default branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build with Vite
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist  # This is where Vite outputs the build
          publish_branch: gh-pages  # Optional: default is gh-pages

📂 Step 5: Push the code to your GitHub repository

Initialize a git repository in your project
```
git init
git checkout -b main
git remote add origin https://github.com/your-username/your-repo-name.git
```
Replace the above url with the one provided in your repository.

Push to GitHub:

git add .
git commit -m "Initial commit"
git push -u origin main

🧭 Step 6: Enable GitHub Pages sourced by gh-pages branch

In your GitHub repo:

Go to Settings → Pages
In the "Build and deployment" section:

For Source, select Deploy from a branch
For Branch, select the gh-pages branch and root (/) folder
Click the Save button

🎉 Beatifully your app should be up and running at "https://your-username.github.io/your-repo-name/" (the one you have defined in the package.json file).

👀 You can also check the executed(s) workflow(s) in your repository at the Actions tab. 🚀