Fix Vite GitHub Pages 404 After Deploy

For project pages, Vite needs the correct base path that matches the repository name. Without it, assets load from the wrong URL and the app appears broken.

Book $50 Deploy Rescue Generate a checklist

Common symptoms

GitHub Pages opens but CSS/JS assets 404.
Refreshing a route shows GitHub Pages 404.
The app works locally but fails under /repo-name/.

What to check first

Platform: Vite + GitHub Pages
Error: 404 after deploy

For project pages, Vite needs the correct base path that matches the repository name. Without it, assets load from the wrong URL and the app appears broken.

Step-by-step fix

Set base in vite.config.js to /your-repo-name/ for GitHub project pages.
Build with npm run build and deploy the dist folder.
For client-side routing, use hash routing or add a SPA fallback strategy supported by your deployment method.
Confirm GitHub Pages source points to the branch/folder that contains the built files.

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  base: "/your-repo-name/"
});

Common mistake to avoid

Do not set base to / for project pages unless the site is served from the root domain.

Still stuck?

Send the deploy log, repository link, target platform, and expected URL. ShipFast Deploy Rescue is a fixed-price debugging service for indie projects and MVPs.

Get Deploy Rescue Email project details