How revalidation works

Each query that opts into caching will be stored on the server. By default, the cached data is considered fresh for 60 seconds. After this period, the data is marked as stale.

When the same query is requested again, the cached data is returned. If the data is stale, it will be revalidated in the background. On your next request, the updated (fresh) data will be served.

  const { data, error } = await serverQuery({
    queryUrl: "https://api.example.com/data",
    queryCache: true
  });

In the example above, since queryCache is set to true, the default revalidation time of 60 seconds will apply.

Setting a custom revalidation time

You can specify a custom revalidation interval by passing a number (in seconds) to the revalidate parameter.

In the example below, the revalidation time is set to 120 seconds:

  const { data, error } = await serverQuery({
    queryUrl: "https://api.example.com/data",
    queryCache: {
      revalidate: 120,
    },
  });

Manual revalidation

You can manually revalidate a query using the revalidateTag function from Next.js's internal next/cache module. This function accepts a tag string and will revalidate all queries associated with that tag.

There are two common ways to use revalidateTag: within an API Route or inside a Server Action.

import { revalidateTag } from "next/cache";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const tag = searchParams.get("tag");

  revalidateTag(tag);

  return new Response("Revalidated", { status: 200 });
}

"use server";
import { revalidateTag } from "next/cache";

export async function revalidateTagAction(tag: string) {
  revalidateTag(tag);
  return { success: true };
}