Next.js on Github Pages

CLONE REPOSITORY

git clone https://github.com/RevanSP/NEXTJS-GHPAGES-EXAMPLE.git
cd NEXTJS-GHPAGES-EXAMPLE
npm install

USING `basePath` FOR STATIC ASSETS

Important: Every time you want to import or reference a file from the public/ folder, you must add basePath in front of the file path. This ensures your assets are always accessible, both locally and on GitHub Pages.

To ensure your static assets work correctly on GitHub Pages, use the basePath from useRouter() in your components:

import { useRouter } from "next/router";

export default function MyComponent() {
  const { basePath } = useRouter();
  return (
    <img src={
      basePath + "/my-image.svg"
    } alt="My Image" />
  );
}

This will automatically prefix your asset paths with the correct base path when deployed to GitHub Pages.

Fetching Data from API with SSG (getStaticProps)

To fetch data from any public API (for example, JSONPlaceholder), you can use getStaticProps for Static Site Generation (SSG). This will fetch the data at build time and generate static HTML.

// pages/example.js
export async function getStaticProps() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts/1');
  const data = await res.json();
  return {
    props: {
      post: data,
    },
  };
}

export default function Example({ post }) {
  return (
    <div>
      <h3>{post.title}</h3>
      <p>{post.body}</p>
    </div>
  );
}

Note: The data will be fetched at build time, so it will not update until you rebuild your site.

Fetching Data from API with ISR (Incremental Static Regeneration)

Tip: Although true ISR (revalidate in getStaticProps) is not supported on GitHub Pages, you can mimic ISR by triggering a rebuild of your site using GitHub Actions workflows (for example, on a schedule or via webhook). This way, your static data can be refreshed periodically, even though your code still uses SSG (getStaticProps).

Workflow Note: The provided GitHub Actions workflow already includes a commented-out schedule block. To enable automatic periodic rebuilds (like ISR), simply uncomment the schedule section in .github/workflows/gh-pages.yml.

# To enable automatic rebuilds (like ISR), uncomment the schedule block below:
# schedule:
#   - cron: '*/30 * * * *'  # Every 30 minutes

Cron format: '*/30 * * * *' means every 30 minutes.
The five fields are:
minute hour day-of-month month day-of-week

minute: 0-59
hour: 0-23
day-of-month: 1-31
month: 1-12
day-of-week: 0-6 (0 = Sunday)

Example: '0 * * * *' = every hour on the hour.
Example: '0 0 * * *' = every day at midnight.

HOSTING ON GITHUB PAGES

Push your project to a new or existing GitHub repository.
Go to your repository's Settings > Pages > Source, then select Deploy from a branch and choose GitHub Actions as the source.
Make sure the .github/workflows/gh-pages.yml workflow file exists in your repository (see this repo for an example).
The workflow will automatically build and deploy your site to GitHub Pages every time you push to the main branch.
After the workflow finishes, your site will be available at:
https://<your-github-username>.github.io/<your-repo-name>/

Next.js Features Not Supported on GitHub Pages

API Routes: You cannot use pages/api or app/api endpoints. All API logic must be handled externally.
Server-Side Rendering (SSR): getServerSideProps is not supported. Only static generation is allowed.
Incremental Static Regeneration (ISR): revalidate and on-demand static regeneration are not available.
Middleware: Edge Middleware and advanced routing logic that require a server are not supported.
Dynamic Routing with Fallback: fallback: true or blocking in getStaticPaths are not supported. Only fallback: false works.
Image Optimization: Next.js image optimization (default loader) is not available. Use unoptimized for images.
Custom Server: You cannot use a custom Express/Node.js server.