Static Export & Deployment

Static Export Overview

The Quantum Advantage Tracker is configured as a Static Site Generation (SSG) project using Next.js. Instead of requiring a Node.js server at runtime, the project is exported into a collection of static HTML, CSS, and JavaScript files. This allows the site to be hosted on high-performance, low-cost platforms like GitHub Pages.

Export Configuration

The static export behavior is defined in next.config.ts. The following settings are critical for successful deployment:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'export',
  basePath: process.env.PAGES_BASE_PATH,
  images: { unoptimized: true },
  typedRoutes: true,
};

export default nextConfig;

Key configuration parameters:

• output: 'export': Enables the static export mode.
• basePath: Utilizes an environment variable (PAGES_BASE_PATH) to handle deployments to sub-directories (e.g., username.github.io/repo-name).
• images.unoptimized: Required because Next.js's default Image Optimization API is not supported in a static environment.

Building the Project

To generate the static files, execute the build script. This will compile the React components and output the production-ready files into a directory named out/.

# Install dependencies
npm install

# Build the project
npm run build

The resulting out/ directory contains the complete website structure, including the index.html files for various routes like /trackers and /participate.

Deployment to GitHub Pages

The project is hosted at quantum-advantage-tracker.github.io.

Automated Deployment

Deployment is typically handled via GitHub Actions. When changes are merged into the main branch, a workflow:

1. Sets up the Node.js environment.
2. Runs npm run build.
3. Uploads the contents of the out/ directory to the gh-pages branch or uses the actions/deploy-pages action.

Environment Variables

If you are deploying to a custom GitHub Pages URL that includes a sub-path, ensure the PAGES_BASE_PATH environment variable is set during the build step:

# Example for a sub-path deployment
PAGES_BASE_PATH=/my-repository-name npm run build

Local Preview of Exported Site

To verify that the static export works correctly before deploying, you can serve the out/ directory locally using a simple web server:

# Using npx and 'serve'
npx serve@latest out

This allows you to test navigation and asset loading in an environment that mimics the final production hosting.