@sctg/vite-plugin-github-pages-spa

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

Star the project

If you appreciate my work, please consider giving it a star! 🤩

Installation

npm install @sctg/vite-plugin-github-pages-spa --save-dev
# or
yarn add @sctg/vite-plugin-github-pages-spa --dev
# or
pnpm add @sctg/vite-plugin-github-pages-spa -D

Usage

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

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react'; // or any other framework plugin
import { githubPagesSpa } from "@sctg/vite-plugin-github-pages-spa";

export default defineConfig({
  // Set base if your repo isn't deployed at the root domain
  // For example, if your GitHub Pages URL is 'https://username.github.io/repo-name/'
  base: '/repo-name/',
  
  plugins: [
    react(),
    githubPagesSpa({
      // Options are optional
      verbose: true, // Set to false to disable console logs
    }),
  ],
});

Options

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