Skip to Content
Core ConceptsCaching and Revalidation

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.

Writing DataCommon Features