Skip to content

feat: set a cache policy - #206

Merged
uniqueg merged 6 commits into
devfrom
feat/204-cache-policy
Nov 20, 2026
Merged

uniqueg merged 6 commits into
devfrom
feat/204-cache-policy

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Sets a cache policy for the site (part of #107), in the headers of next.config.js, so that the Docker image and Vercel send the same Cache-Control headers:

Paths Cache-Control
/_next/static/ (hashed JS, CSS, fonts) public, max-age=31536000, immutable (Next.js default, can't be overridden)
/_next/image the source image's max-age, at least 4 hours (Next.js default)
Pages public, max-age=0, must-revalidate
Other files of public/ public, max-age=86400, stale-while-revalidate=604800
robots.txt, sitemap*.xml public, max-age=3600
sw.js no-cache, no-store, must-revalidate

Pages are revalidated on every request because Next.js sends s-maxage=31536000 for prerendered pages. A shared cache could then serve a page for a year after a deploy, for example a reverse proxy in front of the Docker host, which Watchtower redeploys without purging anything. That page would point at /_next/static/ files the new image no longer has. With max-age=0, must-revalidate, caches revalidate by ETag (a 304), so deploys show at once.

public/sw.js is not changed: offline support (#205) is left to the maintainers. It only gets a header, so that browsers always fetch the clean-up worker fresh.

  • next.config.js: the rules, with comments.
  • src/test/cache-policy.test.ts: compiles the rules with Next.js's own buildCustomRoute, the function next build uses. It checks which header applies to pages, files, crawler files, sw.js and /_next/, and that every file in public/ gets the policy meant for it.
  • README.md: new section "Caching" under "Deployment".

Verification

  • Test first: the new test failed (18/18) before the config change and passes after it. A mutation check (renaming the sw.js rule) makes 2 tests fail.
  • npx prettier --check "src/**/*.{ts,tsx,json,css}": passes. README.md has a formatting difference in its link references that was there before; the new section is formatted.
  • npx tsc --noEmit: passes.
  • npm run lint: passes.
  • npm run test:coverage: 10 files, 106 tests passed.
  • npm run build: passes (all routes static, sitemap generated).
  • Standalone server, run as in the Docker image (node .next/standalone/server.js with public/ and .next/static copied), checked with curl -D -. The adversarial reviewer repeated this independently and got the same results.
    • /, /products: public, max-age=0, must-revalidate. If-None-Match with the ETag gives 304.
    • /products with RSC: 1, /nodes/ (redirect): same page header.
    • /nonexistent, /missing.png (404): private, no-cache, no-store, max-age=0, must-revalidate (unchanged, set by Next.js).
    • /elixir.png, /favicon.ico, /flags/de.svg, /ELIXIR%20On-Cloud%20Logo%20Pack/On-Cloud_MONO.svg: public, max-age=86400, stale-while-revalidate=604800.
    • /robots.txt, /sitemap.xml, /sitemap-0.xml: public, max-age=3600.
    • /sw.js: no-cache, no-store, must-revalidate.
    • /_next/image?url=%2Felixir.png&w=128&q=75: public, max-age=86400, must-revalidate.
    • /_next/static/chunks/*.js: public, max-age=31536000, immutable.
  • Before the change, the same server sent s-maxage=31536000 for pages and public, max-age=0 for all files of public/.
  • Vercel preview: not checked. The preview is behind Vercel's login (every path answers 302). Vercel applies the headers of next.config.js as documented.
  • CI (run 44366723005): all checks pass, including Audit and CI passed. npm has dropped GHSA-fc5q-39xc-vjpf, which GitHub withdrew on 2026-11-18; fix: make next-sitemap a dev dependency #208 (for fix: keep next-sitemap out of production audit #207) also keeps build-only tools out of the audit from now on.

Review

adversarial-reviewer and quality-reviewer ran on origin/dev...HEAD. Neither found anything high. The fixes are in d89d25e and 2168a32:

  • Medium (quality): the public/ check accepted any rule for files. It now expects the specific rule for robots.txt, the sitemaps and sw.js.
  • Medium (quality): the test imports a Next.js internal. A comment now says why: it is the matcher next build uses.
  • Low (both): the README now says that stale-while-revalidate can serve an old public/ file once more within a week. It now says that 404s for unknown paths are not cached, because a direct GET /404 gets the page rule. The image TTL is marked as the Next.js default, the page rule's comment says it covers any path without an extension, and the sw.js row links to the PWA note.

These fixes only changed tests, comments and docs, not logic, so no second round was needed.

Declined review findings

  • Medium (quality): add a server-level smoke test to CI (build, start, curl). Declined for this PR: the real server was checked by hand and by the adversarial reviewer with the same results, and a server-level test job would be a CI change of its own. The unit test checks the rule order Next.js documents.
  • Low (quality): check decoded paths with spaces. The adversarial reviewer confirmed against the running server that the encoded logo-pack path gets the file rule.
  • Low (adversarial): a direct GET /404 gets public, max-age=0, must-revalidate. Caches must revalidate it on every request, so it's harmless; the README now says so rather than adding a rule.

Open questions

None.

Closes #204

🤖 Generated with Claude Code

Summary by Sourcery

Set explicit cache policies for site responses so deployments revalidate pages promptly while caching static assets appropriately.

New Features:

  • Define consistent cache-control policies for pages, public assets, crawler files, and the service worker across Docker and Vercel deployments.

Enhancements:

  • Document the site's caching behavior and deployment implications in the README.

Documentation:

  • Add a Deployment documentation section describing cache lifetimes, revalidation, and asset replacement guidance.

Tests:

  • Add coverage for cache-rule matching across pages, public files, crawler files, the service worker, and Next.js-managed paths.

Set Cache-Control headers in next.config.js, so that the Docker image
and Vercel send the same ones. Pages are revalidated on every request
instead of Next.js's s-maxage of a year, which would let a shared cache
serve pages that point at /_next/static/ files of an older image. Files
of public/ are cached for a day, robots.txt and the sitemaps for an
hour, and sw.js not at all. Hashed /_next/static/ files keep Next.js's
immutable header.

A test matches paths against the rules the way Next.js does and checks
that every file of public/ gets a rule for files. The README documents
the policy.

Closes #204

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 17, 2026
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
landing-page Ready Ready Preview Nov 20, 2026 5:54pm UTC

@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Configuration

Define cache-control rules in Next.js for pages, public assets, crawler files, and the service worker, while leaving Next.js-managed asset caching intact.

  • next.config.js L3-49, L65-67

Documentation

Document the cache policies, their deployment implications, and when to rename public assets to avoid stale cached files.

  • README.md L196-222

Tests

Test the effective cache rule for representative paths and verify that every file in public/ receives its intended policy.

  • src/test/cache-policy.test.ts L1-104

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 49.86%. Comparing base (f4cf5d0) to head (0300bfc).

Additional details and impacted files
@@           Coverage Diff           @@
##              dev     #206   +/-   ##
=======================================
  Coverage   49.86%   49.86%           
=======================================
  Files          44       44           
  Lines        1105     1105           
  Branches      292      292           
=======================================
  Hits          551      551           
  Misses        479      479           
  Partials       75       75           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

uniqueg and others added 2 commits November 18, 2026 18:56
The check for public/ accepted any rule for files, so robots.txt,
the sitemaps or sw.js could silently fall back to the rule for other
files. Expect the specific rule for each of them instead.

Also say why the test imports a Next.js internal, that the image TTL
is a Next.js default, that the page rule covers any path without an
extension, and link the sw.js row to the note on the old PWA.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
stale-while-revalidate lets a cache serve an old file of public/ once
more within a week after its day, and a direct request for /404 gets
the page rule. Say so instead of promising a day and no cached 404s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg

uniqueg commented Nov 20, 2026

Copy link
Copy Markdown
Member Author

@sourcery-ai review

@sourcery-ai

sourcery-ai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Linked issues

Checked at commit 0300bfc

#204 feat: configure a cache policy · 1 of 1 met

# Requirement Status Notes
1 Configure Cache-Control policies for static assets and HTML pages for Vercel and Docker deployments. ✅ Met The shared next.config.js headers define page and public-file policies; Next.js retains its defaults for /_next/static/ and /_next/image. The Docker image runs the built standalone Next.js server, so it uses the same configuration.

@uniqueg
uniqueg merged commit fce06b5 into dev Nov 20, 2026
25 checks passed
@uniqueg
uniqueg deleted the feat/204-cache-policy branch November 20, 2026 17:56

This branch was successfully deployed

1 active deployment
Preview – landing-page — 0300bfc5 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: configure a cache policy

1 participant