Caching and Revalidation

next-nexus uses tags and revalidate in a unified definition for both server and client caching.

Basics

• Default Cache Policy: If server.cache is omitted, next-nexus defaults to no-store. This ensures dynamic behavior across all Next.js versions. For static caching or ISR, you must explicitly set `server.cache: ‘force-cache’.
• Configuration in definition:
  • server: { cache, revalidate, tags } → Maps to Next.js fetch options (cache, next.revalidate, next.tags) to control server-side caching and ISR.
  • client: { revalidate, tags } → Controls the in-memory cache policy on the client.
• Cache Key: A stable cache key is derived from the definition object, including any parameters.
• ETags: Conditional requests are made using ETags to avoid re-downloading unchanged data.

Definition Example (Factory Usage Required)

import { createNexusDefinition } from "next-nexus";
 
export const createApiDefinition = createNexusDefinition({
  baseURL: "https://api.example.com",
  retry: { count: 1, delay: 1 },
  timeout: 5,
});
 
export const postsDefinition = {
  list: createApiDefinition<Post[]>({
    method: "GET",
    endpoint: "/posts",
    server: { cache: "force-cache", revalidate: 120, tags: ["posts"] },
    client: { revalidate: 120, tags: ["posts"] },
  }),
};

Revalidating After Writes

• Client cache: Call revalidateClientTags(['posts']).
• Server cache (ISR): Call await revalidateServerTags(['posts']) inside a Server Action or Route Handler.

Tips

• Use a combination of broad tags (e.g., ['posts']) for collections and granular tags (e.g., ['post:123']) for individual items.
• The revalidate option controls the staleness window of the cache, which is separate from a CDN’s TTL.
• The combination of ETags and hydration minimizes network traffic when data has not changed.

See also: Revalidation, Definitions.