GitHub Pages Deployment

GitHub Pages Deployment

The Quantum Advantage Tracker is built as a static site using Next.js and is hosted on GitHub Pages. The deployment follows the Static Site Generation (SSG) pattern, where the application is pre-rendered into static HTML, CSS, and JavaScript files.

Configuration

The deployment behavior is controlled by settings in next.config.ts. Key configurations include:

• Static Export: The output: 'export' setting ensures that npm run build generates an out/ directory containing the static assets.
• Image Optimization: Since GitHub Pages does not support the default Next.js Image Optimization API, images.unoptimized is set to true.
• Base Path: The site supports deployment to subdirectories via the PAGES_BASE_PATH environment variable.

Environment Variables

When deploying to GitHub Pages, you must configure the following environment variable if the site is not hosted at the root of a domain:

| Variable | Description | Example | | :--- | :--- | :--- | | PAGES_BASE_PATH | The path prefix for the repository. If deploying to https://<user>.github.io/<repo>, set this to /<repo>. | /quantum-advantage-tracker |

Deployment Process

To deploy a new version of the tracker, follow these steps:

1. Build the project: Generate the static files by running the build script. If you are deploying to a specific subpath, ensure the environment variable is set during this step.

   # For root domain deployment
   npm run build
   
   # For subpath deployment (e.g., /QAT)
   PAGES_BASE_PATH=/QAT npm run build
   

2. Upload Assets: The resulting out/ directory contains the production-ready files. These should be pushed to the gh-pages branch or handled via a GitHub Action.

Automated Deployment (GitHub Actions)

The repository is configured to deploy automatically via GitHub Actions whenever changes are merged into the main branch. The workflow typically:

1. Sets up the Node.js environment.
2. Installs dependencies via npm install.
3. Executes npm run build.
4. Uploads the out/ directory to GitHub Pages.

Custom Domains

The tracker is currently accessible at: https://quantum-advantage-tracker.github.io

If you are forking this repository to host your own tracker, ensure that the Pages settings in your GitHub repository are set to deploy from the appropriate branch or a custom GitHub Action.