GitHub Actions: How to Deploy Your React Application with Vite to GitHub Pages

Learn how to automatically deploy a React application created with Vite to GitHub Pages using GitHub Actions. This step-by-step guide covers the entire process, from configuration to publication.

Prerequisites

• A React application created with Vite.
• A repository hosted on GitHub.
• Basic familiarity with GitHub Actions.

Step 1: Configure GitHub Actions Workflow

Create a file named gh_pages.yml in the .github/workflows directory and add the following content:

name: Deploy React Vite App to GitHub Pages

on:
  push:
    branches:
      - main  # Branch that triggers deployment
  workflow_dispatch:

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

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

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Install dependencies
        run: npm ci

      - name: Build with Vite
        run: npm run build

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v1

      - 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-20.04
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Detailed Workflow Explanation:

on: Specifies the workflow triggers (push to the main branch or manual trigger).
permissions: Grants access to read content, write to Pages, and issue authentication tokens.
concurrency: Prevents simultaneous executions of the workflow.

Jobs:

Job build:

• Checkout repository: Copies the repository contents to the virtual machine.
• Setup Node.js: Installs Node.js version 20.
• Install dependencies: Installs dependencies specified in package-lock.json using npm ci.
• Build with Vite: Generates static files for the project using npm run build.
• Setup Pages: Configures GitHub Pages to accept deployment.
• Upload artifact: Uploads the contents of the dist folder to GitHub Actions.

Job deploy:

• Deploy to GitHub Pages: Deploys the generated files to GitHub Pages.

Step 2: Adjusting the Build Script for Single Page Applications (SPA)

Because applications created with React and Vite are SPAs, GitHub Pages struggles to handle internal routes. To overcome this, update the build script in your package.json file:

{
  "build": "tsc -b && vite build && cp dist/index.html dist/404.html"
}

Explanation:

• tsc -b: Compiles the project if you are using TypeScript.
• vite build: Builds static files.
• cp dist/index.html dist/404.html: Copies index.html to 404.html, ensuring GitHub Pages correctly redirects all internal routes in your SPA. There are numerous alternative ways to handle this, but this is the quickest and easiest.

Step 3: Enable GitHub Pages in Your Repository

To enable GitHub Actions to deploy your site to GitHub Pages:

• Go to your GitHub repository.
• Navigate to Settings → Pages.
• Under Build and deployment, select GitHub Actions as the source.

Step 4: Deploy

Now, every time you push to the main branch, your site will automatically deploy to GitHub Pages. Access your site using the URL provided by GitHub Pages after deployment (e.g., <your_username>.github.io).

Conclusion

Following these steps, you'll have your React application created with Vite hosted for free on GitHub Pages with full support for internal routes.

Support My Work!

Check out these recommended books for developers. All links redirect to Amazon, where you can purchase the books.

---

Note: Amazon Affiliate Links. If you buy a book through these links, I receive a small commission, helping me maintain my contributions (articles, open-source code, etc.) and produce more quality content. Thank you!