Nextjs Cache Architecture

// lib/cache/revalidate.ts
//
// Every `updateTag()` call in the project lives here.
// Mutations import these functions — they never call `updateTag()` directly.
//
// Why centralize:
//   - One place to audit invalidation behavior.
//   - One place to change the strategy (e.g., add observability).
//   - Mutations stay focused on data changes, not cache mechanics.

"use server";

import { updateTag } from "next/cache";
import { CACHE_TAGS } from "./tags";

function updateTags(tags: string[]) {
  // Optional: add observability here. Because every invalidation flows
  // through this one function, a single console.log / OpenTelemetry span
  // gives full coverage with no per-call-site instrumentation.
  // Example:
  //   console.log("[cache] updateTag", { tags, at: new Date().toISOString() });
  for (const tag of tags) updateTag(tag);
}

// Bulk — any entry in the collection changed.
// Replace [Collection] / [collection] with the user's real names.
export async function revalidate[Collection]Cache() {
  updateTags([CACHE_TAGS.[collection]]);
}

// Surgical — one specific entry changed.
// Only export this if `CACHE_TAGS.[entity]` factory exists in tags.ts.
// Always invalidate the parent collection too — list views read from it.
export async function revalidate[Entity]Cache(id: string | number) {
  updateTags([
    CACHE_TAGS.[collection],
    CACHE_TAGS.[entity](id),
  ]);
}


// components/SuspenseOnSearchParams.tsx
//
// A standard <Suspense> does NOT re-trigger its fallback on client-side
// navigation when only `searchParams` changes — the boundary is keyed on
// the route, not the query string. This wrapper re-keys the boundary on
// every searchParams change so the fallback shows during the new fetch.
//
// Use this on every page that has search or filter params.

"use client";

import { useSearchParams } from "next/navigation";
import { Suspense, type ReactNode } from "react";

type Props = {
  fallback: ReactNode;
  children: ReactNode;
};

export default function SuspenseOnSearchParams({ fallback, children }: Props) {
  const searchParams = useSearchParams();
  return (
    <Suspense key={searchParams.toString()} fallback={fallback}>
      {children}
    </Suspense>
  );
}


// lib/cache/tags.ts
//
// Single source of truth for every cache tag in the project.
// Raw tag strings are never written anywhere else.
//
// Conventions:
//   - Lowercase only.
//   - Entity tags use `domain:id` format.
//   - Match the actual data model — do not invent names.
//   - Add an entity factory ONLY when a mutation needs `updateTag()`
//     on a single entry. Otherwise the collection tag is enough.
//
// Type safety:
//   `as const satisfies TagRegistry` keeps every value literal-typed
//   (so the compiler knows `CACHE_TAGS.posts` is exactly `"posts"`)
//   AND enforces that every entry is either a tag string or a factory
//   that returns one. Misuse — e.g. dropping in a number, an object,
//   or a function with the wrong signature — fails to compile.

type Tag = string;
type EntityTagFactory = (id: string | number) => Tag;
type TagRegistry = Record<string, Tag | EntityTagFactory>;

export const CACHE_TAGS = {
  // COLLECTION TAGS — one per logical data group, always present.
  // Replace [collection] with the user's real collection name.
  [collection]: "[collection]",
  [anotherCollection]: "[anotherCollection]",

  // ENTITY TAG FACTORIES — only when a mutation targets a single entry.
  // Replace [entity] with the user's real entity name.
  [entity]: ((id) => `[entity]:${id}`) satisfies EntityTagFactory,
} as const satisfies TagRegistry;


{
  "skill_name": "nextjs-cache-architecture",
  "evals": [
    {
      "id": 1,
      "name": "greenfield-posts-with-comments",
      "prompt": "I'm building a blog in Next.js 16 (App Router). I have a `posts` table and a `comments` table — every post has many comments. I need a posts listing page at /posts, a post detail page at /posts/[slug] showing the post and its comments, and a da