Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/retrowin/llms.txt

Use this file to discover all available pages before exploring further.

RetroWin is a fully static site — after running the Vite build, the output is a directory of plain HTML, CSS, and JavaScript files with zero server-side dependencies. This means you can host it on any service that can serve static files: GitHub Pages, Netlify, Vercel, Cloudflare Pages, an S3 bucket, or even a USB drive. No Node.js runtime, no database, no backend.

​
Build for production

1

Run the production build

From the project root, run:
npm run build
Vite compiles and bundles the React app into a dist/ directory. The output includes a root index.html, hashed asset filenames under dist/assets/, and the static page files under dist/pages/.
2

Preview the build locally

Before deploying, verify the production bundle with Vite’s built-in preview server:
npm run preview
The app is served at http://localhost:4173. This runs the actual compiled output — not the dev server — so it’s the closest thing to testing in production without leaving your machine.
3

Deploy the dist/ folder

Upload or push the contents of dist/ to your hosting provider of choice. The sections below cover GitHub Pages, Netlify, and Vercel specifically.

​
GitHub Pages

GitHub Pages is the most natural fit for a portfolio project — it’s free, it’s built into every public repo, and it serves static files with zero configuration.
1

Push your repository to GitHub

Make sure your built dist/ contents (or source, if using a GitHub Actions workflow) are committed and pushed to your main branch.
2

Enable Pages in repository settings

Go to Settings → Pages. Under Source, choose Deploy from a branch, then select main and / (root) as the folder. GitHub Pages will begin serving your site at https://<your-username>.github.io/<repo-name>/.For a more automated workflow, configure a GitHub Actions deployment instead: create a .github/workflows/deploy.yml that runs npm run build and deploys the dist/ output using the peaceiris/actions-gh-pages action or the official actions/deploy-pages action.
3

(Optional) Configure a custom domain

Add a CNAME file to the root of your repository containing your domain name (e.g. retrowin.dev). Then point your domain’s DNS to GitHub’s servers per the GitHub Pages custom domain docs.
RetroWin uses React Router’s HashRouter, which means every URL looks like https://yoursite.com/#/about rather than https://yoursite.com/about. The fragment (#/about) is never sent to the server — GitHub Pages always receives a request for / and returns index.html, and then the React app reads the hash to render the correct page. This is why no redirect rules or 404.html tricks are needed on GitHub Pages.

​
Netlify

Netlify auto-detects Vite projects and can run your build pipeline on every push. Because RetroWin uses hash-based routing, no redirect configuration is needed. There is no risk of Netlify returning a 404 for a path like /about because those paths simply don’t exist in a hash-router app — navigation is entirely client-side. For reference, if you ever migrate to BrowserRouter in the future, you would need a netlify.toml like this to redirect all requests back to index.html:
netlify.toml
[[redirects]]
  from = "/*"
  to   = "/index.html"
  status = 200
With HashRouter as it stands today, you can deploy to Netlify by connecting your GitHub repository and setting the build command to npm run build and the publish directory to dist. No netlify.toml required.

​
Vercel

Vercel provides one-click deploys from GitHub. Import your repository at vercel.com/new, select the project, and Vercel will auto-detect the Vite framework preset — setting npm run build as the build command and dist as the output directory automatically. As with Netlify, hash routing means you do not need a vercel.json with rewrite rules. All routing happens in the browser after index.html is loaded, so Vercel never needs to resolve sub-paths on the server.

​
Static page files

The pages/ directory contains pre-rendered HTML stubs for each route — About.html, Projects.html, and so on. These files are nearly identical to the root index.html but include a small inline script at the top of <head>:
pages/About.html
<script>
  window.__STATIC_PAGE_ROUTE__ = "/about";
  if (!window.location.hash || window.location.hash === "#/" || window.location.hash === "#") {
    window.location.hash = "/about";
  }
</script>
What this does: When someone navigates directly to yoursite.com/pages/About.html (e.g. from a bookmarked or shared link), the script checks whether a hash route is already present. If not, it sets window.location.hash to /about before the React app boots. The app then reads the hash, matches it to the /about route, and renders the About page — making the direct URL behave exactly as if the user had clicked the About icon on the desktop. This pattern allows shareable deep-links on any static host without any server-side logic.
Do not switch RetroWin from HashRouter to BrowserRouter (HTML5 history mode) unless you have confirmed that your hosting provider will redirect all 404s back to index.html. On GitHub Pages and most static hosts, a direct request to yoursite.com/about returns a real 404 because no file exists at that path. HashRouter avoids this entirely — the server always sees a request for / and the hash fragment is handled purely by the browser.
If you deploy to GitHub Pages and your assets fail to load, check for a .nojekyll file in the repository root. GitHub Pages runs Jekyll by default, which silently ignores any file or directory whose name starts with an underscore (_). Vite outputs assets to dist/assets/ — which is fine — but if you have any _ prefixed directories, add an empty .nojekyll file to the root to disable Jekyll processing and ensure all files are served correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us