Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/web-weaver/llms.txt

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

Web Weaver compiles to a fully static site — once you run the build command, the dist/ folder contains everything needed to serve the portfolio with no server-side runtime. You can host it on GitHub Pages for free, connect it to Netlify or Vercel in minutes, or drop it onto any static file host. This guide covers the build output structure and step-by-step deployment for each platform.

​
Running the Build

From the project root, run: 
npm run build
Vite compiles, bundles, and fingerprints all assets, then writes the production output to dist/. The build typically completes in under 10 seconds.

​
What’s in dist/

dist/
├── index.html          # Root entry point — loads the SPA
├── .nojekyll           # Prevents GitHub Pages from running Jekyll
├── assets/
│   ├── main.js         # All components and page logic (bundled + minified)
│   ├── main.css        # Design tokens, fonts, and Tailwind output
│   ├── proxy.js        # Internal routing proxy
│   └── index.js        # Vite entry bootstrap
└── pages/
    ├── About.html
    ├── Blog.html
    ├── Projects.html
    └── ...             # One HTML file per route for direct linking
Every file in pages/ is a thin HTML shell that sets window.__STATIC_PAGE_ROUTE__ before loading assets/main.js. This lets the SPA boot directly into the right route when a visitor lands on a deep link.
Web Weaver uses hash-based routing (#/about, #/projects, etc.). Because the route lives after the #, the browser never actually requests /about from the server — only index.html is ever fetched. This means deep links work out of the box on any static host without configuring server-side redirects or rewrite rules.

​
GitHub Pages

1

Build the project

Run npm run build to generate the dist/ folder with all production assets.
2

Push dist/ to the gh-pages branch

The simplest approach is to push the contents of dist/ directly to a gh-pages branch. You can do this manually or with a tool like gh-pages:
npx gh-pages -d dist
This command creates (or force-pushes) the gh-pages branch with only the contents of dist/ — your source code stays on main.
3

Configure Pages in repository settings

In your GitHub repository, go to Settings → Pages. Under Branch, select gh-pages and set the folder to / (root). Click Save.GitHub will provide your live URL in the format https://<username>.github.io/<repo-name>/.
4

Verify the .nojekyll file

The dist/ folder already contains a .nojekyll file (created by the Vite build). This file tells GitHub Pages to serve your files as-is and skip Jekyll processing — without it, directories and files beginning with _ are silently ignored, which would break asset loading.No action needed; just confirm the file is present in your deployed branch.

​
Subdirectory Deployment

If your site is served from a subdirectory (e.g. https://username.github.io/web-weaver/ rather than the root), you must tell Vite about the base path so asset URLs are generated correctly. Open vite.config.js and set the base option:
vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  base: '/web-weaver/',   // ← match your repository name exactly
});
After saving, run npm run build again. All asset URLs in the output will be prefixed with /web-weaver/, which is what GitHub Pages expects when serving from a project sub-path.
If you’re deploying to a custom domain (e.g. https://morganweaver.dev), the site is at the root — set base: '/' (the default) and leave vite.config.js unchanged.

​
Netlify

1

Connect your repository

Log in to Netlify, click Add new site → Import an existing project, and authorise GitHub. Select your Web Weaver repository.
2

Configure the build settings

Netlify will auto-detect Vite in most cases. Confirm or set these values:
SettingValue
Build commandnpm run build
Publish directorydist
Node version18 or later (set in Environment Variables as NODE_VERSION = 18)
3

Deploy

Click Deploy site. Netlify runs your build command, publishes dist/, and gives you a *.netlify.app URL immediately.Every push to your default branch triggers an automatic redeploy. Pull requests get their own Deploy Preview URL.
Because Web Weaver uses hash routing, Netlify’s default configuration handles all navigation correctly — the hash fragment is never sent to the server, so there is no need for a _redirects file or netlify.toml catch-all rule.

​
Vercel

1

Import your repository

Log in to Vercel, click Add New → Project, and import your Web Weaver repository from GitHub.
2

Configure the build settings

Vercel auto-detects Vite. Verify the defaults:
SettingValue
Framework PresetVite
Build Commandnpm run build
Output Directorydist
3

Deploy

Click Deploy. Vercel builds the project and publishes it to a *.vercel.app domain. Like Netlify, every push triggers a redeploy and PRs get preview URLs.
Hash routing works on Vercel without any extra configuration. If you ever switch to path-based routing in the future, add a vercel.json to the project root to handle the SPA catch-all:
vercel.json
{
  "rewrites": [
    { "source": "/((?!assets|pages).*)", "destination": "/index.html" }
  ]
}
In a standard SPA using path routing (e.g. /about), the browser requests /about from the server. If the server doesn’t know about that path, it returns a 404. The common fix is a catch-all redirect rule that sends every unknown path to index.html.Hash routing works differently. The URL https://yoursite.com/#/about tells the browser to request https://yoursite.com/ — the root — and then hand #/about to JavaScript on the client. The # fragment is never sent to the server at all. This means index.html is always the file served, and React Router reads the hash to decide which component to render. No server configuration needed.

​
Continuous Deployment with GitHub Actions

For a fully automated pipeline that builds and deploys on every push, add this workflow file to your repository:
.github/workflows/deploy.yml
name: Deploy Web Weaver

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
This workflow runs npm run build and then publishes dist/ to the gh-pages branch automatically on every push to main. No manual npx gh-pages -d dist step needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us