adding future testing instructions and massively simplfying/fixing the cache build step

Author: williamdalessandro

.github/workflows/build-pr-preview.yml

@@ -2,6 +2,10 @@ name: Build Preview
 run-name: 'Build Preview for "${{ github.event.pull_request.title }}" (#${{ github.event.pull_request.number }})'
 
 on:
+  # 1: Change this to `pull_request` to see changes while testing this file in a PR.
+  # 2: This is because `pull_request_target` only works from the context of the base branch
+  #    https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target
+  # 3: Change this back to `pull_request_target` before merge for security reasons
   pull_request:
     types: [opened, synchronize]
   # Hello Security 👋, we are checking to make sure forked repo PR changed paths are only in content/** inside the job security-check.
@@ -105,17 +109,11 @@ jobs:
           cache: 'npm'
           node-version-file: 'package.json'
 
-      - name: Use cache
+      - name: Cache Next.js build
         uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf # v4.2.2
         with:
-          path: |
-            ~/.npm
-            ${{ github.workspace }}/.next/cache
-          # Only invalidate cache when actual build dependencies change (not content files)
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('scripts/**/*.{js,mjs}', 'app/**/*.{ts,tsx}', 'next.config.js', 'productConfig.mjs') }}
-          # Fallback to cache with same dependencies, even if build scripts differ
-          restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
+          path: ${{ github.workspace }}/.next/cache
+          key: ${{ runner.os }}-nextjs-build-${{ hashFiles('package-lock.json', 'next.config.js') }}
 
       - name: Install Vercel CLI
         run: npm i --global vercel@latest
@@ -184,18 +182,6 @@ jobs:
         with:
           repository: hashicorp/dev-portal
           path: ./unified-docs-frontend-preview
-      - name: Use cache
-        uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf # v4.2.2
-        with:
-          path: |
-            ~/.npm
-            ${{ github.workspace }}/unified-docs-frontend-preview/.next/cache
-          # Generate a new cache whenever packages or source files change.
-          # However, we could potentially have this only cache based on package changes.
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx', '**/*.mdx') }}
-          # If source files changed but packages didn't, rebuild from a prior cache.
-          restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
 
       - name: Setup Node.js
         uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
@@ -204,6 +190,12 @@ jobs:
           cache-dependency-path: 'unified-docs-frontend-preview/package-lock.json'
           node-version-file: 'unified-docs-frontend-preview/package.json'
 
+      - name: Cache Next.js build
+        uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf # v4.2.2
+        with:
+          path: ${{ github.workspace }}/unified-docs-frontend-preview/.next/cache
+          key: ${{ runner.os }}-nextjs-build-devportal-${{ hashFiles('unified-docs-frontend-preview/package-lock.json', 'unified-docs-frontend-preview/next.config.js') }}
+
       - name: Setup Vercel CLI
         run: npm i --global vercel@latest