How to deploy NextJS project on Github pages ?

In this article, I actually wanted to talk about the GitHub pages that I researched and tried completely for my needs. For a long time, I had in mind to prepare a small portfolio page and open it live. I sat down and created this using next js and tailwind. I will not share the codes here, but if you visit and like it, you can access all the codes on GitHub.

Coming to our topic, GitHub pages actually enable the related content to be hosted instantly through a created GitHub repository and seen as a website. We will raise the NextJS project that we have created here with the NextJS deploy .yml file, which is already ready in GitHub.
Let’s get started.

First we create a GitHub repo with your GitHub username. For example, my GitHub username is cmracar and the repository I created is cmracar.github.io. After the repository is created, let’s move on to the Actions section through the tabs. Then let’s proceed with the New Workflow button.

Here, when we type “next” in the search box, the workflow we want will appear.

After selecting the workflow, a file structure in the form of .github/workflows was created in our repo. In fact, if you have experience in creating a .yml file, you can manually add your file under .github/workflows. If we go back to the code, we have a structure like the following.

# Sample workflow for building and deploying a Next.js site to GitHub Pages
#
# To get started with Next.js see: https://nextjs.org/docs/getting-started
#
name: Deploy Next.js site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Detect package manager
        id: detect-package-manager
        run: |
          if [ -f "${{ github.workspace }}/yarn.lock" ]; then
            echo "manager=yarn" >> $GITHUB_OUTPUT
            echo "command=install" >> $GITHUB_OUTPUT
            echo "runner=yarn" >> $GITHUB_OUTPUT
            exit 0
          elif [ -f "${{ github.workspace }}/package.json" ]; then
            echo "manager=npm" >> $GITHUB_OUTPUT
            echo "command=ci" >> $GITHUB_OUTPUT
            echo "runner=npx --no-install" >> $GITHUB_OUTPUT
            exit 0
          else
            echo "Unable to determine packager manager"
            exit 1
          fi
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: "16"
          cache: ${{ steps.detect-package-manager.outputs.manager }}
      - name: Setup Pages
        uses: actions/configure-pages@v2
        with:
          # Automatically inject basePath in your Next.js configuration file and disable
          # server side image optimization (https://nextjs.org/docs/api-reference/next/image#unoptimized).
          #
          # You may remove this line if you want to manage the configuration yourself.
          static_site_generator: next
      - name: Restore cache
        uses: actions/cache@v3
        with:
          path: |
            .next/cache
          # Generate a new cache whenever packages or source files change.
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
          # If source files changed but packages didn't, rebuild from a prior cache.
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
      - name: Install dependencies
        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
      - name: Build with Next.js
        run: ${{ steps.detect-package-manager.outputs.runner }} next build
      - name: Static HTML export with Next.js
        run: ${{ steps.detect-package-manager.outputs.runner }} next export
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./out

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

I did not make any additional edits in the file in my own use, but you can make additional edits if you wish. As a note, I can add that I wanted the deploy operation to be triggered when I open a pull request to the main branch and lines 9 and 10 in my .yml file. I edited the lines accordingly. But GitHub says it can only do this for push to main branch, so I didn’t make this change either.

After creating our file, we had a new workflow. There is a different workflow called GitHub Pages that GitHub already offers, we need to remove it because we have 2 workflows running constantly and we don’t want our readme file to go live.

Let’s go to the Settings tab in the repository and select it from the Pages tab as follows. Here, GitHub Pages offered by GitHub are selected and we change it to GitHub Actions.

After all these operations, we can observe the flow process in the Actions tab with a new push operation. If a successful deploy operation has taken place, we will see that our website is up. Afterwards, we can visit our website from the browser with the repository name we created. For example https://cmracar.github.io.

Sources: GitHub Actions