This project is a single-page app (SPA) with client-side routing. To run it on GitHub Pages you need to:
- Set the correct base path (so assets load under
https://<user>.github.io/<repo>/). - Serve
index.htmlfor all routes so the SPA handles/blog,/about, etc. (GitHub Pages does not do this by default; the workflow below copiesindex.htmlto404.htmlso missing paths fall back to the app).
For a project site (e.g. https://<username>.github.io/security-slam/), the app must be served under the repo name.
Edit vite.config.ts and set base to your repository path (leading and trailing slashes):
export default defineConfig({
plugins: [react()],
base: "/security-slam/", // Use your actual repo name
build: {
outDir: "dist"
}
});If the repo is my-website, use base: "/my-website/".
For a user or organization site (e.g. https://<username>.github.io/), use base: "/" and skip the trailing path in the URL when opening the site.
A workflow is included that builds the app and deploys the dist/ folder to GitHub Pages.
-
Push the repo (including
.github/workflows/ci.yaml) to GitHub. -
Enable GitHub Pages in the repo:
- Settings → Pages.
- Under Build and deployment, set Source to GitHub Actions.
-
Trigger a deploy: push to the default branch (e.g.
main) or run the CI workflow from the Actions tab. Pull requests run thebuildjob only; deploys happen frommain. -
After the run finishes, the site is available at:
- Project site:
https://<username>.github.io/<repo>/ - User/org site:
https://<username>.github.io/
- Project site:
The workflow:
- Uses the Node version in
.nvmrc, runsnpm ci --ignore-scripts,npm run typecheck, andnpm run build. - Copies
dist/index.htmltodist/404.htmlso unknown paths (e.g./blog/welcome) return the SPA and React Router can handle them. - Uploads
dist/as the Pages artifact and deploys viadeploy-pages.
If you prefer not to use Actions:
-
Set
baseinvite.config.tsas in step 1. -
Build locally:
npm run build
-
Copy the SPA fallback so routing works:
cp dist/index.html dist/404.html
-
Deploy the contents of
dist/:- Option A: Push
dist/to agh-pagesbranch (e.g. with gh-pages:npx gh-pages -d dist). - Option B: In Settings → Pages, choose Deploy from a branch, select the branch and the folder that contains
dist/(e.g./ (root)if you push only the built files).
- Option A: Push
-
In Settings → Pages, set the branch (and folder) to the one that holds the built site.
To use a custom domain (e.g. www.example.com):
- Add a CNAME file in the built output with the domain (one line). The Actions workflow does not add one by default; you can add a step that writes it into
dist/before upload, or addCNAMEtopublic/so it is copied intodistduring build. - In the repo Settings → Pages, under Custom domain, enter the domain and save.
- Configure DNS with your provider (CNAME or A records as instructed by GitHub).
After the first deploy, allow a few minutes for the site to appear. If assets fail to load, double-check that base in vite.config.ts matches your Pages URL path (e.g. /<repo>/ for a project site).