@trieb.work/nextjs-turbo-redis-cache 1.15.0 → 1.16.0

package/.cursor/skills/testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: testing
+description: >-
+  Run tests and add Next.js version coverage for the cache handler. Use when
+  running tests, adding a new Next.js version to the test matrix, creating test
+  apps, or debugging CI failures.
+---
+
+# Testing
+
+## Running Tests
+
+```bash
+# Unit tests (fast, no Redis needed)
+pnpm test:unit
+pnpm test:unit:watch          # watch mode
+pnpm test:unit:coverage       # with coverage
+
+# Integration tests (needs Redis + pre-built Next.js app)
+pnpm test:integration
+pnpm test:integration:build-id-prefix
+pnpm test:integration:cache-components
+
+# E2E / Playwright for cached components (needs Redis, auto-starts Next.js app)
+pnpm test:e2e
+```
+
+## Test Structure
+
+```
+test/
+├── playwright/              # E2E (Playwright browser tests)
+├── vitest/
+│   ├── unit/                # Unit tests (no external deps)
+│   └── integration/         # Integration tests (Redis + Next.js)
+│       └── cache-components/
+└── nextjs-test-projects/    # Shared Next.js app fixtures
+```
+
+For details on each layer, see `test/README.md`.
+
+## Adding a New Next.js Version
+
+### 1. Standard Integration Test App
+
+For testing the core cache handler against a new Next.js version (e.g. 16.5.0):
+
+```bash
+cp -r test/nextjs-test-projects/next-app-16-2-6 test/nextjs-test-projects/next-app-16-5-0
+rm -rf test/nextjs-test-projects/next-app-16-5-0/{node_modules,.next,pnpm-lock.yaml}
+```
+
+Edit `test/nextjs-test-projects/next-app-16-5-0/package.json`:
+
+- Change `"name"` to `"next-app-16-5-0"`
+- Change `"next"` version to `"16.5.0"`
+- Change `"eslint-config-next"` version to `"16.5.0"`
+
+Then add the app to the CI integration matrix in `.github/workflows/ci.yml`:
+
+```yaml
+# In the `integration` job → strategy.matrix.next-test-app
+- next-app-16-5-0
+```
+
+### 2. Cache Components Test App (Next.js 16+ only)
+
+If the new version supports `use cache` / `cacheTag` / `cacheLife`:
+
+```bash
+cp -r test/nextjs-test-projects/next-app-16-2-6-cache-components test/nextjs-test-projects/next-app-16-5-0-cache-components
+rm -rf test/nextjs-test-projects/next-app-16-5-0-cache-components/{node_modules,.next,pnpm-lock.yaml}
+```
+
+Edit the `package.json`:
+
+- Change `"name"` to `"next-app-16-5-0-cache-components"`
+- Change `"next"` to `"16.5.0"`
+- Change `"eslint-config-next"` to `"16.5.0"`
+
+Then add it to both CI matrix jobs in `.github/workflows/ci.yml`:
+
+```yaml
+# In `integration-cache-components` → strategy.matrix.cache-components-app
+- next-app-16-5-0-cache-components
+
+# In `e2e` → strategy.matrix.cache-components-app
+- next-app-16-5-0-cache-components
+```
+
+### 3. Checklist After Adding
+
+- [ ] `package.json` has correct Next.js version + matching `eslint-config-next`
+- [ ] `"@trieb.work/nextjs-turbo-redis-cache": "file:../../../"` path is correct
+- [ ] No leftover `node_modules/`, `.next/`, or `pnpm-lock.yaml` from the copy
+- [ ] CI matrix updated (integration and/or cache-components + e2e)
+- [ ] `test/README.md` → "Next.js Test Projects" table updated
+- [ ] Run `cd test/nextjs-test-projects/next-app-16-5-0 && pnpm install && pnpm build` to verify it builds
+
+### 4. Removing a Version
+
+Remove the folder, remove it from the CI matrix entries, and update `test/README.md`.
+
+## Environment Variables
+
+| Variable               | Default                            | Purpose                                   |
+| ---------------------- | ---------------------------------- | ----------------------------------------- |
+| `NEXT_TEST_APP`        | `next-app-15-4-11`                 | Which app for `pnpm test:integration`     |
+| `CACHE_COMPONENTS_APP` | `next-app-16-2-6-cache-components` | Which app for cache-components tests      |
+| `PLAYWRIGHT_TEST_APP`  | `next-app-16-2-6-cache-components` | Which app Playwright starts               |
+| `PLAYWRIGHT_BASE_URL`  | `http://localhost:3101`            | Override to use an already-running server |
+| `SKIP_BUILD`           | —                                  | Skip Next.js build in integration tests   |
+| `DEBUG_INTEGRATION`    | —                                  | Print child process output                |
+
+## Writing New Tests
+
+- **Unit tests**: Add `*.test.ts` in `test/vitest/unit/`. No Redis, no Next.js. Use mocks.
+- **Integration tests**: Add `*.test.ts` in `test/vitest/integration/`. Spawn Next.js, use `fetch()`, check Redis.
+- **E2E tests**: Add `*.spec.ts` in `test/playwright/`. Use Playwright browser automation.
+
+Unit tests use `.test.ts` extension. Playwright tests use `.spec.ts` extension.

package/.github/workflows/ci.yml

@@ -8,31 +8,15 @@ on:
     branches:
       - main
 
-# Default-deny: every job inherits read-only access. Jobs that need more
-# elevate explicitly via their own `permissions:` block (see `build` below).
 permissions:
   contents: read
 
 jobs:
-  build:
+  lint-and-unit:
     runs-on: ubuntu-latest
     permissions:
-      contents: read # Required for actions/checkout
-      pull-requests: write # Required for the coverage-comments action on PRs
-    strategy:
-      matrix:
-        include:
-          - next-test-app: next-app-15-0-3
-            run-cache-components: false
-          - next-test-app: next-app-15-3-2
-            run-cache-components: false
-          - next-test-app: next-app-15-4-7
-            run-cache-components: false
-          - next-test-app: next-app-16-0-3
-            run-cache-components: true
-          - next-test-app: next-app-16-2-3
-            run-cache-components: true
-
+      contents: read
+      pull-requests: write
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -47,8 +31,6 @@ jobs:
           cache: 'pnpm'
 
       - name: Install dependencies
-        # --ignore-scripts blocks lifecycle scripts of all dependencies to mitigate
-        # supply-chain attacks via compromised postinstall hooks.
         run: pnpm install --ignore-scripts
 
       - name: Run lint
@@ -57,6 +39,51 @@ jobs:
       - name: Build project
         run: pnpm build
 
+      - name: Run unit tests
+        run: pnpm test:unit:coverage
+
+      - name: Code Coverage Comments
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        uses: kcjpop/coverage-comments@v2.2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          coverage-file: './coverage/lcov.info'
+
+      - name: Dry run the release
+        if: github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release --dry-run
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    strategy:
+      matrix:
+        next-test-app:
+          - next-app-15-4-11
+          - next-app-16-0-11
+          - next-app-16-2-6
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
+
+      - name: Build project
+        run: pnpm build
+
       - name: Start Redis
         uses: supercharge/redis-github-action@1.8.0
         with:
@@ -69,63 +96,114 @@ jobs:
       - name: Configure Redis Keyspace Notifications
         run: redis-cli config set notify-keyspace-events Exe
 
-      - name: Install Integration Test Project
-        run: cd test/integration/${{ matrix.next-test-app }} && pnpm install
+      - name: Install test project
+        run: cd test/nextjs-test-projects/${{ matrix.next-test-app }} && pnpm install
 
-      - name: Build Integration Test Project
-        run: cd test/integration/${{ matrix.next-test-app }} && pnpm build
+      - name: Build test project
+        run: cd test/nextjs-test-projects/${{ matrix.next-test-app }} && pnpm build
 
-      - name: Run tests
-        run: pnpm test:ci
+      - name: Run integration tests
+        run: pnpm test:integration
         env:
           SKIP_BUILD: true
           NEXT_TEST_APP: ${{ matrix.next-test-app }}
 
-      - name: Install Cache Components Integration Test Project
-        if: matrix.run-cache-components
-        run: cd test/integration/next-app-16-2-3-cache-components && pnpm install
+  integration-pages:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
 
-      - name: Build Cache Components Integration Test Project
-        if: matrix.run-cache-components
-        run: cd test/integration/next-app-16-2-3-cache-components && pnpm build
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'pnpm'
 
-      - name: Run Cache Components integration tests
-        if: matrix.run-cache-components
-        run: pnpm test:cache-components
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
 
-      - name: Run Redis kill/restart E2E test (cache-components)
-        if: matrix.run-cache-components
-        run: pnpm vitest --run --config vitest.cache-components.config.ts test/cache-components/redis-kill-reconnect.spec.ts
+      - name: Build project
+        run: pnpm build
 
-      - name: Install Playwright browsers
-        if: matrix.run-cache-components
-        run: pnpm exec playwright install --with-deps
+      - name: Start Redis
+        uses: supercharge/redis-github-action@1.8.0
+        with:
+          redis-version: '7'
+          redis-port: 6379
 
-      - name: Run Playwright E2E tests
-        if: matrix.run-cache-components
-        run: pnpm test:e2e
+      - name: Install redis-cli
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+
+      - name: Configure Redis Keyspace Notifications
+        run: redis-cli config set notify-keyspace-events Exe
+
+      - name: Install test project
+        run: cd test/nextjs-test-projects/next-pages-16-2-6 && pnpm install
+
+      - name: Build test project
+        run: cd test/nextjs-test-projects/next-pages-16-2-6 && pnpm build
+
+      - name: Run Pages Router integration tests
+        run: pnpm test:integration:pages
         env:
-          PLAYWRIGHT_BASE_URL: http://localhost:3101
+          SKIP_BUILD: true
 
-      - name: Code Coverage Comments
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
-        uses: kcjpop/coverage-comments@v2.2
+  integration-build-id-prefix:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
         with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          coverage-file: './coverage/lcov.info'
+          node-version: '22'
+          cache: 'pnpm'
 
-      - name: Dry run the release
-        if: github.event_name == 'pull_request'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub token for Semantic Release
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # NPM token for publishing
-        run: |
-          npx semantic-release --dry-run
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Start Redis
+        uses: supercharge/redis-github-action@1.8.0
+        with:
+          redis-version: '7'
+          redis-port: 6379
 
-  build-id-prefix:
+      - name: Install redis-cli
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+
+      - name: Configure Redis Keyspace Notifications
+        run: redis-cli config set notify-keyspace-events Exe
+
+      - name: Install test project
+        run: cd test/nextjs-test-projects/next-app-15-4-11 && pnpm install
+
+      - name: Build test project
+        run: cd test/nextjs-test-projects/next-app-15-4-11 && pnpm build
+
+      - name: Run BUILD_ID prefix integration test
+        run: pnpm test:integration:build-id-prefix
+
+  integration-cache-components:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
+    needs: lint-and-unit
+    strategy:
+      matrix:
+        cache-components-app:
+          - next-app-16-0-11-cache-components
+          - next-app-16-2-6-cache-components
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -142,8 +220,55 @@ jobs:
       - name: Install dependencies
         run: pnpm install --ignore-scripts
 
-      - name: Run lint
-        run: pnpm lint
+      - name: Build project
+        run: pnpm build
+
+      - name: Start Redis
+        uses: supercharge/redis-github-action@1.8.0
+        with:
+          redis-version: '7'
+          redis-port: 6379
+
+      - name: Install redis-cli
+        run: sudo apt-get update && sudo apt-get install -y redis-tools
+
+      - name: Configure Redis Keyspace Notifications
+        run: redis-cli config set notify-keyspace-events Exe
+
+      - name: Install test project
+        run: cd test/nextjs-test-projects/${{ matrix.cache-components-app }} && pnpm install
+
+      - name: Build test project
+        run: cd test/nextjs-test-projects/${{ matrix.cache-components-app }} && pnpm build
+
+      - name: Run cache-components integration tests
+        run: pnpm test:integration:cache-components
+        env:
+          CACHE_COMPONENTS_APP: ${{ matrix.cache-components-app }}
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit
+    strategy:
+      matrix:
+        cache-components-app:
+          - next-app-16-0-11-cache-components
+          - next-app-16-2-6-cache-components
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --ignore-scripts
 
       - name: Build project
         run: pnpm build
@@ -160,11 +285,16 @@ jobs:
       - name: Configure Redis Keyspace Notifications
         run: redis-cli config set notify-keyspace-events Exe
 
-      - name: Install Integration Test Project
-        run: cd test/integration/next-app-15-4-7 && pnpm install
+      - name: Install test project
+        run: cd test/nextjs-test-projects/${{ matrix.cache-components-app }} && pnpm install
 
-      - name: Build Integration Test Project
-        run: cd test/integration/next-app-15-4-7 && pnpm build
+      - name: Build test project
+        run: cd test/nextjs-test-projects/${{ matrix.cache-components-app }} && pnpm build
 
-      - name: Run BUILD_ID integration test
-        run: pnpm test:integration:build-id-prefix
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps
+
+      - name: Run Playwright E2E tests
+        run: pnpm test:e2e
+        env:
+          PLAYWRIGHT_TEST_APP: ${{ matrix.cache-components-app }}

package/.github/workflows/release.yml

@@ -22,11 +22,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      - name: Create GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - name: Checkout code
         uses: actions/checkout@v6
         with:
           # Need full history so the post-release audit can diff against pre-release SHA.
           fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Capture pre-release SHA
         id: pre
@@ -65,7 +73,7 @@ jobs:
 
       - name: Run Semantic Release
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # GitHub token for Semantic Release
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} # GitHub App token (bypasses required_signatures ruleset)
           NPM_CONFIG_PROVENANCE: 'true'
         run: pnpm exec semantic-release