Vite Plugin: GitHub Pages SPA Support

A Vite plugin that enables seamless Single Page Application (SPA) support when hosting on GitHub Pages. GitHub Pages doesn't natively support SPAs, which can cause 404 errors when users refresh the page or navigate directly to a route. This plugin solves that problem by:

1. Creating a 404.html file that redirects all requests to your SPA
2. Injecting a script in your index.html that handles the redirection

Installation

1npm install @sctg/vite-plugin-github-pages-spa --save-dev
2# or
3yarn add @sctg/vite-plugin-github-pages-spa --dev
4# or
5pnpm add @sctg/vite-plugin-github-pages-spa -D

Usage

Add the plugin to your vite.config.ts or vite.config.js:

1import { defineConfig } from 'vite';
2import react from '@vitejs/plugin-react'; // or any other framework plugin
3import { githubPagesSpa } from "@sctg/vite-plugin-github-pages-spa";
4
5export default defineConfig({
6  // Set base if your repo isn't deployed at the root domain
7  // For example, if your GitHub Pages URL is 'https://username.github.io/repo-name/'
8  base: '/repo-name/',
9  
10  plugins: [
11    react(),
12    githubPagesSpa({
13      // Options are optional
14      verbose: true, // Set to false to disable console logs
15    }),
16  ],
17});

Options

Option	Type	Default	Description
verbose	boolean	true	Whether to show log messages during build
injectScript	boolean	true	Whether to inject the redirection script into index.html
custom404Html	string	undefined	Optional custom HTML content for the 404.html file

How It Works

The plugin implements the SPA GitHub Pages technique by:

1. Adding a script to your index.html that checks for special query parameters and redirects correctly
2. Creating a 404.html file that handles GitHub Pages 404 errors by redirecting to your index page with those special query parameters

Credits

This plugin is based on the technique described by Rafael Pedicini at spa-github-pages.

License

MIT