Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
86 lines (67 loc) · 2.68 KB

DEPLOYMENT.md

File metadata and controls

86 lines (67 loc) · 2.68 KB
Raw

GitHub Pages Deployment Guide

Overview

This project is now configured with React Router DOM's HashRouter for GitHub Pages compatibility. Hash-based routing ensures all routes work correctly when deployed to GitHub Pages.

Current Configuration

✅ Completed Setup

  • React Router DOM: Installed and configured with HashRouter
  • Navigation: Updated to use React Router DOM components (NavLink, useLocation)
  • Build Process: Successfully tested - creates optimized production build in dist/public/
  • gh-pages: Installed as dev dependency for deployment

📝 Required Package.json Updates

To complete the GitHub Pages setup, you need to manually add these to your package.json:

{
  "homepage": "https://your-username.github.io/your-repo-name",
  "scripts": {
    "build:client": "NODE_ENV=production vite build",
    "predeploy": "npm run build:client",
    "deploy": "gh-pages -d dist/public"
  }
}

Deployment Instructions

1. Update your package.json

  • Add the homepage field with your GitHub Pages URL
  • Add the build and deployment scripts shown above

2. Deploy to GitHub Pages

# Build and deploy in one command
npm run deploy

# Or manually:
npm run build:client
npx gh-pages -d dist/public

3. Configure GitHub Repository

  1. Go to your GitHub repository settings
  2. Navigate to "Pages" section
  3. Set source to "Deploy from a branch"
  4. Select the gh-pages branch
  5. Your app will be available at the homepage URL

How It Works

Hash Routing

  • URLs use hash format: https://your-site.com/#/profile
  • GitHub Pages serves index.html for all routes
  • React Router handles navigation client-side
  • Perfect for static hosting environments

Build Output

  • Production build creates optimized files in dist/public/
  • Includes all assets, CSS, and JavaScript bundles
  • Ready for static hosting deployment

Deployment Process

  1. npm run build:client - Creates production build
  2. gh-pages -d dist/public - Deploys build folder to gh-pages branch
  3. GitHub Pages automatically serves from gh-pages branch

Troubleshooting

Common Issues

  • 404 on routes: Ensure you're using HashRouter (already configured)
  • Assets not loading: Check homepage field matches your GitHub Pages URL
  • Build fails: Run npm run build:client to test build process

Verification

  • ✅ Hash symbol (#) appears in URLs when navigating
  • ✅ Page refreshes work correctly on any route
  • ✅ Direct URL access works for all routes

Next Steps

  1. Update your package.json with the required fields
  2. Run npm run deploy to deploy to GitHub Pages
  3. Configure your GitHub repository Pages settings
  4. Your React app will be live on GitHub Pages!