Setting Up a GitHub Workflow Script to Host Your Vite React Application on <username>.github.io

Vite React website hosted from my github repository.

Hello everyone,

Recently, I encountered a challenge while hosting my portfolio, which I developed using Vite React and Three.js. In my quest to find the ideal hosting solution, I explored numerous resources. The majority recommended using GitHub Pages with the `gh-pages` library. However, this approach typically results in URLs formatted as `<username>.github.io/<repo-name>`, but I was aiming for a simpler URL format: `<username>.github.io`.

To achieve this, I ventured into setting up a GitHub Workflow. But first, let’s demystify what a GitHub Workflow is.

A GitHub Workflow is a set of automated processes that you can set up in your GitHub repository to build, test, package, release, or deploy any code project on GitHub. Workflows are defined by a YAML file checked into the .github/workflows directory of a repository. These workflows are an integral part of GitHub Actions, which is a continuous integration (CI) and continuous deployment (CD) platform.

Certainly, here’s an improved version of your statement:

It’s important to note that the YAML script for a GitHub Workflow can vary depending on the versions of your libraries and Node.js. To give you a better idea and for reference, here’s my `package.json` file:

{
  "name": "portfolio",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "homepage": "https://anirudhrawat.github.io/",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist",
    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "@emailjs/browser": "^3.12.1",
    "@react-three/drei": "^9.96.1",
    "@react-three/fiber": "^8.15.14",
    "framer-motion": "^10.18.0",
    "maath": "^0.10.7",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-parallax-tilt": "^1.7.201",
    "react-router-dom": "^6.21.3",
    "react-tilt": "^1.0.2",
    "react-vertical-timeline-component": "^3.6.0",
    "three": "^0.160.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.43",
    "@types/react-dom": "^18.2.17",
    "@vitejs/plugin-react": "^4.2.1",
    "autoprefixer": "^10.4.17",
    "eslint": "^8.55.0",
    "eslint-plugin-react": "^7.33.2",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.5",
    "gh-pages": "^6.1.1",
    "postcss": "^8.4.33",
    "tailwindcss": "^3.4.1",
    "vite": "^5.0.8"
  }
}

To set up the workflow, we’ll go through the following steps. I’ll explain each step in detail afterward:

1. Create a public GitHub repository and push your code to it.
2. In the root directory of your project, create a folder named `.github`.
3. Within the `.github` folder, create another folder named `workflows`.
4. Inside the `workflows` folder, create a file named `deploy.yml`.
5. Go to your repository settings, navigate to `Actions` > `General`.
6. In the `General` settings, adjust your workflow permissions to ‘Read and write permissions’. Refer to the screenshot below for guidance:

Set your workflow permissions

In the deploy.yml file add the following code:

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload dist repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Explaination for above code:

Sure, let’s break down each significant line of the GitHub workflow configuration:

# Simple workflow for deploying static content to GitHub Pages

This is a comment explaining the purpose of the file, which is to deploy static content to GitHub Pages.

name: Deploy static content to Pages

Sets the name of the workflow as “Deploy static content to Pages.

on:

Specifies when the workflow should be triggered.

push:
 branches: [‘main’]

Triggers the workflow on a `push` event to the `main` branch.

workflow_dispatch:

Allows the workflow to be manually triggered from the GitHub Actions tab.

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

Sets the permissions for the workflow:
— `contents: read` allows reading the repository content.
— `pages: write` allows writing (deploying) to GitHub Pages.
— `id-token: write` allows writing an ID token for authentication purposes.

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

Manages concurrency:
— `group: ‘pages’` groups all runs of this workflow in the same concurrency group named ‘pages’.
— `cancel-in-progress: true` means if a new run starts, any currently running workflow in the same group will be canceled.

jobs:

Defines one or more jobs. Jobs are a series of steps that execute on the same runner.

deploy:

Declares a job named ‘deploy’.

environment:
 name: github-pages
 url: ${{ steps.deployment.outputs.page_url }}

Sets the environment for the job. It names the environment ‘github-pages’ and assigns the URL from the deployment step’s output as an environment variable.

runs-on: ubuntu-latest

Specifies that the job runs on the latest Ubuntu runner provided by GitHub.

steps:

Begins the definition of the steps that the job will execute.

- name: Checkout
 uses: actions/checkout@v4

- name: Set up Node
 uses: actions/setup-node@v3
 with:
 node-version: 18
 cache: ‘npm’

Sets up Node.js environment:
— `node-version: 18` specifies to use Node.js version 18.
— `cache: ‘npm’` enables caching of npm dependencies.

- name: Install dependencies
 run: npm install

Runs `npm install` to install the project dependencies.

- name: Build
 run: npm run build

Executes the build script defined in `package.json` to build the project.

- name: Setup Pages
 uses: actions/configure-pages@v3

Uses the `actions/configure-pages@v3` action to configure GitHub Pages.

- name: Upload artifact
 uses: actions/upload-pages-artifact@v2
 with:
 path: ‘./dist’

Uploads the build artifacts (from the `dist` directory) using the `actions/upload-pages-artifact@v2` action.

- name: Deploy to GitHub Pages
 id: deployment
 uses: actions/deploy-pages@v2

The final step uses the `actions/deploy-pages@v2` action to deploy the uploaded artifacts to GitHub Pages.

Each line of the workflow is a step in the process of automating the deployment of your project to GitHub Pages whenever changes are pushed to the main branch or when the workflow is manually triggered.

To stay tuned with my projects, here is the link to my portfolio.