GitHub-Pages-Deployment-Setup.md

GitHub Pages Deployment Setup

This document outlines the GitHub Pages deployment process for the trauma-informed UI project, which can be refactored and reused for other projects.

Overview

The deployment uses a combination of GitHub Actions, Vite build system, and the gh-pages package to automatically deploy static files to GitHub Pages.

Live Site: https://github.com/Festa-Design-Studio/trauma-informed-ui

Deployment Architecture

1. GitHub Actions Workflow

Location: .github/workflows/deploy.yml

The workflow typically includes:

• Trigger: Pushes to main branch
• Build Process: Uses Vite to generate static files
• Deploy: Pushes built files to gh-pages branch

2. Package.json Configuration

Key deployment scripts:

{
  "scripts": {
    "build": "npm run build:icons && vite build",
    "build:icons": "node scripts/generateSprite.js",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  },
  "devDependencies": {
    "gh-pages": "^x.x.x"
  }
}

3. Vite Configuration for Static Generation

Location: vite.config.js

Critical requirement: All HTML files must be explicitly listed

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, "index.html"),
        typography: resolve(__dirname, "src/components/atoms/typography.html"),
        buttons: resolve(__dirname, "src/components/atoms/buttons.html"),
        // Add each new HTML file here
      }
    }
  }
});

Static Build Policy

Implemented: June 2024

Core Principles

1. Static-First: All dynamic includes are inlined at build time
2. Explicit File Management: Every HTML file must be declared in Vite config
3. Build Validation: All components tested in static build before completion
4. Navigation Integrity: Links point only to files that exist in build output

Benefits

• Reliability: Eliminates runtime 404 errors
• Performance: Faster loading with pre-built static files
• Compatibility: Works with any static hosting service
• Maintenance: Clear dependency tracking

Deployment Process

Automatic Deployment

1. Push to Main Branch
2. GitHub Actions Triggers
3. Build Process Runs:
   • Generate icon sprites
   • Build static files with Vite
   • Output to dist folder
4. Deploy to GitHub Pages
5. Site Updates Live

Manual Deployment

# Build the project
npm run build

# Deploy to GitHub Pages
npm run deploy

Build Process Details

1. Icon Generation

npm run build:icons

• Script: scripts/generateSprite.js
• Purpose: Creates SVG sprite for trauma-informed icons
• Output: Optimized icon assets

2. Static File Generation

vite build

• Input: Source files and components
• Processing: Inlines includes, optimizes assets
• Output: Static files in dist folder

3. Asset Handling

• Images processed and optimized
• CSS bundled and minified
• JavaScript modules compiled
• HTML files generated for each component

Common Issues & Solutions

404 Errors on Deployed Site

Cause: HTML file not included in vite.config.js

Solution: Add missing file to rollupOptions.input

input: {
  // ...existing files...
  newPage: resolve(__dirname, "src/components/path/new-page.html")
}

Navigation Broken After Deploy

Cause: Links pointing to files not in build output

Solution: Ensure all linked HTML files are:

1. Added to Vite config
2. Present in dist after build
3. Using correct relative paths

Assets Not Loading

Cause: Incorrect path configuration for GitHub Pages subdirectory

Solution: Configure base path in Vite config:

export default defineConfig({
  base: '/repository-name/',
  // ...other config
});

Reusable Implementation Guide

For New Projects

1. Copy Workflow Structure

   • .github/workflows/deploy.yml
   • Adapt repository-specific settings

2. Setup Package Scripts

   • Install gh-pages dependency
   • Configure build and deploy scripts

3. Configure Build Tool

   • Setup Vite or similar static site generator
   • Implement explicit file input system

4. Implement Static Build Policy

   • Replace dynamic includes with build-time generation
   • Add validation for all HTML files

5. Setup Asset Pipeline

   • Configure icon/image processing
   • Optimize for static deployment

6. Documentation

   • Create troubleshooting guide
   • Document file addition process

Required Dependencies

{
  "devDependencies": {
    "vite": "^x.x.x",
    "gh-pages": "^x.x.x"
  }
}

Project Structure

project/
├── .github/workflows/
│   └── deploy.yml
├── src/
│   └── components/
├── scripts/
│   └── generateSprite.js
├── dist/ (generated)
├── vite.config.js
├── package.json
└── DEVELOPMENT_RULES.md

Best Practices

1. Test Locally: Always test build output before deploying
2. Validate Links: Ensure all navigation works in static build
3. Monitor Builds: Watch GitHub Actions for deployment status
4. Document Changes: Update file lists when adding new pages
5. Backup Strategy: Keep build configuration in version control

Maintenance

• Regular Updates: Keep dependencies current
• Build Monitoring: Check deployment logs for errors
• Performance Review: Monitor site speed and optimization
• Documentation Updates: Keep setup instructions current

This deployment setup prioritizes reliability and maintainability, making it ideal for documentation sites and design systems that require consistent availability.