Vite to live in 5 minutes! The Lazy Dev’s Guide to GitHub Pages

Deploy vite app to github pages, free and easiest.

So, I whipped up this totally rad, mind-blowingly awesome Vite app the other day, aaand I needed some, y’know, ridiculously over-the-top, overpriced way to flex it. Just kidding :  I wanted the laziest, smoothest way to slap it online, and boom :  GitHub Pages, baby.

Alright, lemme walk you through it :  easy peasy, no stress. By the end of this guide, you’ll be able to deploy your Vite app to GitHub Pages quickly, easily, and with minimal fuss.

If you’re using createBrowserRouter with RouterProvider like me, you might find yourself on the verge of a meltdown :  until you realize there’s a simple config tweak to make it work. Don’t worry.

5 Easy Steps to Get Your Vite App Online

It’s just a few commands away:

1. Look, I’m assuming you have Git and GitHub set up. If not, take a moment to question your life choices :  then go set them up. We’ll wait.

2. Tell Vite Where to Look:

Open vite.config.js and add the base option, setting it to "/your-repo-name/". Example:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  base: "/my-vite-site/"
});

3. Install gh-pages:

npm install gh-pages --save-dev

This package handles deployments for you.

4. Update package.json:

Add these scripts inside the scripts section:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist",
  "dev": "vite",
  "build": "vite build"
}

Also, set the homepage field to your GitHub Pages URL:

"homepage": "https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/"

5. Deploy It:

npm run deploy

This builds your Vite app and throws it onto the gh-pages branch.

One Last Thing on GitHub

After deployment, head over to your repo settings, find the Pages section, and set the source to gh-pages. Boom :  your app is now live at **https://YOUR_USERNAME.github.io/YOUR_REPO_NAME/.

If You’re Using createBrowserRouter with RouterProvider

You need to add a basename so the routing doesn’t break. Example:

const router = createBrowserRouter(
  [
    { path: "/", element: <Home /> },
    { path: "/projects/:projectId", element: <ProjectDetail /> }
  ],
  { basename: "/my-vite-site" } // Matches repo name to avoid routing 404s
);

Make sure this basename matches the base in vite.config.js and the repo name in package.json.

404 after deploy? Double-check your base and basename match your repo name exactly.

Done and Deployed

That’s it! Your Vite app is online, looking good, and running smoothly. Now you can sit back, sip your coffee, and enjoy.

If this guide saved you even 5 minutes of frustration, drop a comment or share it with a fellow dev who still deploys like it’s 2015. Let’s save each other from deployment nightmares

Vite to live in 5 minutes! The Lazy Dev’s Guide to GitHub Pages was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Originally published on Medium.