Skip to content

github-pages-deployment.md

Latest commit

 

History

History
175 lines (127 loc) · 5.74 KB

github-pages-deployment.md

File metadata and controls

175 lines (127 loc) · 5.74 KB
Raw

GitHub Pages Deployment Guide

This document outlines the deployment process for CodeStorm Hub using GitHub Pages with automated GitHub Actions workflow.

Overview

CodeStorm Hub is deployed using GitHub Pages with a Next.js static export. The deployment process is fully automated through GitHub Actions, which builds and deploys the site whenever changes are pushed to the main branch.

Architecture

  • Framework: Next.js 15 with static export (output: 'export')
  • Deployment Platform: GitHub Pages
  • Automation: GitHub Actions workflow
  • Branch: main (production deployment)
  • Build Output: Static HTML/CSS/JS files in /out directory

Deployment Configuration

1. Next.js Configuration (next.config.ts)

The application is configured for static export with GitHub Pages optimizations:

const nextConfig: NextConfig = {
  output: 'export',
  trailingSlash: true,
  images: {
    unoptimized: true, // Required for GitHub Pages
    remotePatterns: [new URL("https://github.com/CodeStorm-Hub.png")],
  },
  // GitHub Pages specific paths
  basePath: process.env.NODE_ENV === 'production' ? '/CodeStorm-Hub.github.io' : '',
  assetPrefix: process.env.NODE_ENV === 'production' ? '/CodeStorm-Hub.github.io/' : '',
};

2. GitHub Actions Workflow (.github/workflows/deploy.yml)

Automated deployment workflow that:

  • Triggers on pushes to main branch and pull requests
  • Can be manually triggered via workflow_dispatch
  • Builds the Next.js application as static files using npm run build:github-pages
  • Creates .nojekyll file to disable Jekyll processing
  • Deploys to GitHub Pages using official GitHub Pages action

3. Critical Files for Deployment

  • .nojekyll: Automatically created during build to prevent GitHub from processing the site with Jekyll (critical for _next directory assets)
  • 404.html: Custom 404 page (automatically generated by Next.js)
  • Asset files: All CSS/JS files in _next/static/ directory with correct basePath prefixes

Deployment Process

Automatic Deployment

  1. Trigger: Push changes to the main branch
  2. Build: GitHub Actions runs npm run build:github-pages
  3. Export: Next.js generates static files in /out directory
  4. Deploy: Files are deployed to GitHub Pages
  5. Live: Site is available at https://codestorm-hub.github.io/CodeStorm-Hub.github.io/

Manual Deployment

You can manually trigger deployment:

  1. Go to the repository's Actions tab
  2. Select "Deploy to GitHub Pages" workflow
  3. Click "Run workflow" on the main branch

Local Testing

To test the GitHub Pages build locally:

# Install dependencies
npm install

# Build for GitHub Pages
npm run build:github-pages

# Serve the static files (optional)
npx serve out

Repository Settings

Ensure the following GitHub repository settings are configured:

Pages Settings

  1. Navigate to Settings → Pages
  2. Source: Deploy from a branch
  3. Branch: Select gh-pages (created automatically by the workflow)
  4. Folder: / (root)

Actions Permissions

  1. Navigate to Settings → Actions → General
  2. Ensure "Allow all actions and reusable workflows" is selected
  3. Under "Workflow permissions", select "Read and write permissions"

Troubleshooting

Common Issues

  1. Build Fails

    • Check the Actions tab for error logs
    • Ensure all dependencies are properly listed in package.json
    • Verify TypeScript compilation passes locally

  2. Assets Not Loading

    • Confirm basePath and assetPrefix are correctly configured
    • Check that images use the Next.js Image component
    • Verify links use Next.js Link component

  3. 404 Errors on Page Refresh

    • This is expected behavior for client-side routing in GitHub Pages
    • The custom 404.html handles fallback routing

  4. Workflow Permissions Error

    • Ensure repository has proper Actions permissions
    • Check that GITHUB_TOKEN has necessary permissions

Validation Steps

After deployment, verify:

  • Site loads at the GitHub Pages URL
  • Navigation works correctly
  • Images and assets load properly
  • All pages are accessible
  • Responsive design works across devices
  • Dark/light mode toggle functions
  • No console errors in browser developer tools

Performance Optimizations

The GitHub Pages deployment includes several optimizations:

  • Static Generation: All pages are pre-generated at build time
  • Asset Optimization: Images and assets are optimized for web delivery
  • Bundle Splitting: JavaScript is split into optimized chunks
  • CSS Optimization: Tailwind CSS is purged of unused styles
  • Caching: Static assets leverage browser caching

Monitoring

Monitor deployment status:

  • Actions Tab: View build and deployment logs
  • Pages Settings: Check deployment status and URL
  • Repository Insights: Monitor site traffic and performance

Maintenance

Regular maintenance tasks:

  • Monitor GitHub Actions workflow runs
  • Update dependencies periodically
  • Review and optimize Core Web Vitals
  • Test deployment after major changes
  • Keep documentation updated

Custom Domain (Optional)

To use a custom domain:

  1. Add a CNAME file to the repository root
  2. Configure DNS records with your domain provider
  3. Update the domain in repository Pages settings
  4. Update basePath and assetPrefix in next.config.ts

Security Considerations

  • All builds run in isolated GitHub Actions environments
  • No sensitive data is exposed in client-side code
  • Dependencies are automatically scanned for vulnerabilities
  • HTTPS is enforced by default on GitHub Pages

For questions or issues with deployment, please refer to the GitHub Pages documentation or open an issue in this repository.