HTTP Cache-Control Headers Explained on a Real Next.js Site

      // Production only. Build chunks are content-hashed there, so a year of
      // immutable caching is safe. Turbopack's dev chunks keep the same name
      // across edits, and this header in development made browsers keep
      // running stale game code for as long as their cache lived — the
      // "sometimes WASD stops working" reports were a mix of old and new
      // modules, not the controller.
      ...(process.env.NODE_ENV === "production"
        ? [
            {
              source: "/_next/static/(.*)",
              headers: [
                {
                  key: "Cache-Control",
                  value: "public, max-age=31536000, immutable",
                }, // Cache static assets for 1 year
              ],
            },
          ]
        : []),

The one-year rule for build chunks, behind a production check. The comment is the lesson: the header is safe only because production chunks are content-hashed, and the same header in development once made browsers run stale game code. The matching rule for images, at lines 157-177, has no such condition because those URLs are served as they are.

      {
        // The films, their posters and captions. A re-render keeps the file
        // names, so only a request carrying the render stamp
        // (lib/film-manifest.ts prints `?v=` on every URL) may be cached as
        // immutable; Cloudflare then serves the films from its edge. A bare
        // URL, from an old link, keeps revalidating against the origin.
        source: "/videos/:path*",
        has: [{ type: "query", key: "v" }],
        headers: [
          {
            key: "Cache-Control",
            value: "public, max-age=31536000, immutable",
          },
        ],
      },

A name that does not change, handled with a condition. has matches only requests that carry a v query parameter, so a re-rendered film is immutable under its stamped URL while a bare URL from an old link keeps revalidating. The comment says Cloudflare then serves these films from its edge.

      {
        // The Archipelago's models, textures and decoders (prd.md §7). Files
        // are content-hashed by scripts/game/build-manifest.mjs, so they can
        // be immutable; Cloudflare then serves every repeat from the edge and
        // the 1 vCPU origin never streams a model twice. The manifest itself
        // is excluded: it is the one file whose name never changes.
        source: "/game/:path((?!manifest\\.json$).*)",
        headers: [
          {
            key: "Cache-Control",
            value: "public, max-age=31536000, immutable",
          },
        ],
      },

The same idea by exclusion. A negative lookahead in the path pattern matches everything under /game/ except manifest.json. Every other file is content-hashed, so it can be immutable; the manifest is the one file whose name never changes, so it gets no year-long promise from this rule.