feat: PR preview deployments on GitHub Pages

.github/workflows/gh-pages.yml

@@ -1,6 +1,7 @@
-# Sample workflow for building and deploying a Next.js site to GitHub Pages
+# Workflow for building and deploying a Next.js site to GitHub Pages (branch-based).
 #
-# To get started with Next.js see: https://nextjs.org/docs/getting-started
+# NOTE: The repository's GitHub Pages source must be set to "Deploy from a branch"
+# (branch: gh-pages, folder: / (root)) in the repository settings for this to work.
 #
 name: Deploy Next.js site to Pages
 
@@ -12,11 +13,9 @@ on:
   # 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
+# Sets permissions of the GITHUB_TOKEN to allow pushing to the gh-pages branch
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  contents: write
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -25,8 +24,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  # Build job
-  build:
+  build-and-deploy:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -53,14 +51,6 @@ jobs:
         with:
           node-version: "20"
           cache: ${{ steps.detect-package-manager.outputs.manager }}
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-        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@v4
         with:
@@ -77,19 +67,12 @@ jobs:
         run: ${{ steps.detect-package-manager.outputs.runner }} npm run build:samples
       - name: Build with Next.js
         run: ${{ steps.detect-package-manager.outputs.runner }} next build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./out
-
-  # Deployment job
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
+        env:
+          NEXT_PUBLIC_BASE_PATH: /quartett-meister
       - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: out
+          # Preserve PR preview directories from being cleaned up on main deployments
+          clean-exclude: pr-preview

.github/workflows/preview.yml

@@ -0,0 +1,80 @@
+# Workflow for building and deploying PR preview deployments to GitHub Pages.
+#
+# Each open PR is deployed to:
+#   https://lotes.github.io/quartett-meister/pr-preview/pr-<number>/
+#
+# Previews are automatically removed when a PR is closed.
+#
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+# Allow writing to the gh-pages branch and commenting on PRs
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: pr-preview-${{ github.event.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        if: github.event.action != 'closed'
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Restore cache
+        if: github.event.action != 'closed'
+        uses: actions/cache@v4
+        with:
+          path: .next/cache
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+          restore-keys: |
+            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
+
+      - name: Install dependencies
+        if: github.event.action != 'closed'
+        run: npm ci
+
+      - name: Build sample ZIPs
+        if: github.event.action != 'closed'
+        run: npm run build:samples
+
+      - name: Build with Next.js
+        if: github.event.action != 'closed'
+        run: npx --no-install next build
+        env:
+          NEXT_PUBLIC_BASE_PATH: /quartett-meister/pr-preview/pr-${{ github.event.number }}
+
+      - name: Ensure .nojekyll at gh-pages root
+        # JamesIves/github-pages-deploy-action places .nojekyll inside the
+        # deployed *folder* (i.e. pr-preview/pr-N/.nojekyll), not at the
+        # gh-pages branch root.  Jekyll silently blocks every directory that
+        # starts with "_", which includes Next.js' "_next/" asset directory.
+        # Deploying a standalone .nojekyll to the branch root fixes that.
+        if: github.event.action != 'closed'
+        run: mkdir /tmp/nojekyll && touch /tmp/nojekyll/.nojekyll
+
+      - name: Deploy .nojekyll to gh-pages root
+        if: github.event.action != 'closed'
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: /tmp/nojekyll
+          clean: false
+
+      - name: Deploy / remove PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: out

next.config.ts

@@ -8,8 +8,10 @@ const nextConfig: NextConfig = {
   typescript: {
     ignoreBuildErrors: false,
   },
+  basePath: process.env.NEXT_PUBLIC_BASE_PATH || '',
   // Allow access to remote image placeholder.
   images: {
+    unoptimized: true,
     remotePatterns: [
       {
         protocol: 'https',
@@ -19,7 +21,7 @@ const nextConfig: NextConfig = {
       },
     ],
   },
-  output: 'standalone',
+  output: 'export',
   transpilePackages: ['motion'],
   webpack: (config, {dev}) => {
     // HMR is disabled in AI Studio via DISABLE_HMR env var.