This guide will walk you through how to Deploy a React app using Vite and Github Pages, which you can serve on your githubUsername.github.io domain for Free 😉, or on a custom domain you own.

My use case: A personal website, but this works for any single-page application.

Note: I initially built this website with a static HTML and CSS, but after the code grew to over 1,000 lines (yikes! I know), I decided to relive my days as a software engineer and write it in React. This guide highlights some of the key challenges I faced deploying React and Vite on Github Pages.

Step 1: Naming Your Repository

As trivial as it is, this first step is more important than it sounds. The name of your GitHub repository directly determines your final URL. To have your website served from https://githubUsername.github.io without a sub-folder, you must name your repository exactly githubUsername.github.io.

For example, if I want the final URL to be https://mengopudding.github.io and my username is mengopudding, I must name my repository mengopudding.github.io. Had I named the repo portfolio, the final URL would be https://mengopudding.github.io/portfolio

Step 2: Create a React App with Vite

While it has been many moons since I’ve written any JavaScript. While I still remember the gist of things (so I thought), the only one command I knew create-react-app, is now considered outdated and there is a new kid on the block: Vite

To get started, open your terminal and run the following command. Choose “React” and choose your flavor when prompted. ~ I went with TypeScript.

npm create vite@latest my-app — —template react-ts

To verify things are working, navigate into your new project and run the standard dev commands:

cd my-app
npm install
npm run dev

You should also see a vite.config.ts file

Step 3: Configure Tailwind CSS

I never used Tailwind in production environment before, the last design system I used was Braid by Seek — but Tailwind seems to be the go-to in the recent years.

You can also follow the official Get started with Vite & Tailwind documentation.

First, install the necessary dependencies for Tailwind CSS.

npm install tailwindcss @tailwindcss/vite

Next, configure the Vite plugin in your vite. See Official docs for configuring your vite plugin.

Your vite.config.ts should look like this.

//vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite' // <- added this import

export default defineConfig({
  plugins: [react(),tailwindcss()], // <- added tailwindcss() to the array
})

Next, add the Tailwind directives to your main CSS file. This is often src/index.css or src/App.css.

 /* App.css or index.css */
@import "tailwindcss";

Tailwind uses a Just-in-Time (JIT) compiler to scan your code and generate only the CSS you need, resulting in much smaller, more efficient CSS files.

To verify Tailwind is working, try adding a class like text-red-500

<h1 className="text-red-500">Vite + React</h1> 

To verify, run npm run dev, visit the localhost and you should see the changes.

Step 4: Configure Vite for Github Pages

This is a critical step that you must get right. By default, Github Pages serves your site from a sub-path (/<your-repo-name>/), but a standard Vite app assumes it’s served from the root (/). You need to tell Vite to build your project with the correct base URL.

Edit your vite.config.ts file and add the base property. See docs for more info.

// vite.config.ts

// If my repo was named https://github.com/mengopudding/mengopudding.github.io
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  base: '/', // <- added line
  plugins: [react(), tailwindcss()],
})

// If my repo was named https://github.com/mengopudding/my-app
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: '/my-app/', // <- remember to include both slashes wrapped in strings
  plugins: [react(), tailwindcss()],
})

The key here is the base property. If your repository is named my-app, your base path would be '/my-app/'.

For a username.github.io repository, the base path is simply /.

Step 5: Add a Deploy Script

We’ll use a helpful package called gh-pages to automate the build and deployment. First, install the package as a development dependency:

npm install -D gh-pages

Next, add a homepage property and the predeploy and deploy scripts to your package.json. Make sure to replace the URL with your own.

"homepage": "https://mengopudding.github.io", // <- lets Github Pages know what the main landing page is
"scripts": {
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview",
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

• The npm run build command takes all of your code and transforms it into a highly efficient bundle,called dist.

• The gh-pages -d dist command essentially says, “use the gh-pages tool to deploy the contents of the dist directory to a new branch called gh-pages in my repository.”

Step 6: Build and Deploy

1. Ensure all your code is committed to your main branch or that your feature branch is merged into main.

2. Bundle up dist folder with the necessary files.

npm run build

Note: You will need to fix any issues like linting or TS complaints. The build must succeed!

3. Now, you can run the deploy script. This will build your app and publish the dist directory to the gh-pages branch on GitHub

npm run deploy

Note: This will automatically create a new branch called gh-pages in your repo, it will publish only the dist folder into the gh-pages branch. Verify this by going to your repo.

Step 7: Finalize Github Pages Configuration

Go to your Github repo

Navigate to Settings > Pages > Build and deployment > Source: Deploy from a branch > select gh-pages branch / (root) > Save

— See Github official docs for publishing source for your Github Pages site

Finally! The app will start to deploy, you can track its deployment through the Actions tab. Once deployed it will provide you with a URL to your app and… VOILA! CONGRATULATIONS🎉

Troubleshooting

All these issues can cause your app to not render once it has been deployed.

Check your build: The most common issue is a failed build. The npm run deploy command will fail if your npm run build command fails. Make sure you don’t have any TypeScript errors or other issues.

Incorrect vite.config.js: Have you correctly set the base property?

Missing scripts in package.json:

• Have you set the homepage key to your repo?
• Have you added the predeploy and deploy script?

If you see errors like MIME type or 404

• Wait a few minutes: It can take a few minutes for Github Pages to process and deploy the new changes to their servers.

• Check paths to assets: Assets are kept in the public/assets folder, to reference these assets it’s best to use relative path, eg./assets/media/hello_world.png

• Cache issue: Sometimes, the browser caches the old version of your site. Clear your site cache and then perform a hard refresh.

Right Click > Inspect > Application > Clear site data > Hard refresh