On-demand revalidation: TYPO3 publishes, Next.js refreshes

The setup this article builds on: Next.js fetches one JSON document per page from TYPO3, every CMS fetch uses cache: 'force-cache', and the catch-all route is force-static. That combination is what makes the frontend fast and the backend quiet — and it caches aggressively on two levels. The rendered page lands in the full route cache, and the TYPO3 JSON lands in Next's Data Cache, which even survives a rebuild.

The consequence: an editor publishes in TYPO3, TYPO3's own cache is fresh — and the site keeps serving the old content, because nothing tells Next.js to drop its copy. A full rebuild would flush it, but coupling editing to deployment is a stopgap, not a workflow. Caching this hard needs a targeted invalidation path (the underlying setup is described in the TYPO3 headless with Next.js guide) — on-demand revalidation is that path.

Everything TYPO3-side lives in a small extension (nito_revalidate on this site): a service that makes the HTTP call, a DataHandler hook that feeds it, and an entry in the backend's clear-cache menu for a full refresh.

The hook collects — and fires once

A single backend action can touch dozens of records (mass edit, copy with children). Firing a webhook per record would hammer the frontend, so the hook only collects affected page IDs and sends one call when the DataHandler is done:

public function processDatamap_afterDatabaseOperations(
    string $status, string $table, string|int $id,
    array $fieldArray, DataHandler $dataHandler
): void {
    $uid = $status === 'new' ? $dataHandler->substNEWwithIDs[$id] : (int)$id;
    $this->collectPageUid($table, $uid, $dataHandler);
}

// Called by the DataHandler at the very end — one POST for the whole run
public function processDatamap_afterAllOperations(DataHandler $dataHandler): void
{
    $this->flush();
}

For pages records the page ID is the record itself; for tt_content and friends it is the pid. At flush time the collected IDs become tags, and the page slugs are queried fresh from pages.slug — not taken from the incoming field array, which is empty for content changes and holds the old value during a slug change.

The service must never break saving

The HTTP call is synchronous inside a backend save. If the frontend is down or slow, the editor must not pay for it — so the call gets a hard timeout and a catch-all:

$response = $this->requestFactory->request($url, 'POST', [
    'headers' => [
        'Content-Type' => 'application/json',
        'x-revalidate-secret' => $secret,
    ],
    'json' => ['tags' => $tags, 'slugs' => $slugs],
    'timeout' => 5,
]);

The whole thing is wrapped in try/catch (\Throwable): a failure is a log entry, never an exception that reaches the DataHandler. With Next.js completely down, the failed call costs about two milliseconds and the record still saves. If the synchronous call ever becomes a problem, the service body can move behind Symfony Messenger without touching hook or controller — but start simple.

Here is the part most write-ups skip: revalidateTag() and revalidatePath() are void. They mark cache entries as stale; the actual re-render happens lazily on the next request. Worse, since Next.js 16 tag revalidation is “eventual” — the first visitor after an invalidation may still see the old page while the refresh runs in the background. And a tag that no fetch carries is a silent no-op. A plain 200 OK therefore confirms only “invalidation executed”, not “the page is fresh”.

The fix is cheap: after invalidating, the route handler fetches each affected page once itself, server-internally (http://127.0.0.1:3000 + slug — same process, no detour through the public edge). That self-request is the first hit after invalidation: it triggers the re-render eagerly, consumes the potentially stale first response, and yields a real per-page result — HTTP status and duration — that goes into the verified array. The editor who saves and reloads sees the new content on the first reload, not the second.

Three deliberate limits keep this honest and fast. The handler verifies at most three slugs per call so the whole round trip stays inside the backend's five-second timeout — further pages are still invalidated, just not eagerly rendered. A failed verification (backend unreachable, broken JSON) shows up as a non-200 entry inside the response body, while the HTTP status stays 200 — an editor's save must never look broken because a health check failed. And for scope: "all" there is no site-wide confirmation — that would be a crawl, which is what the deploy rebuild is for; the handler verifies the front page as a sample and leaves it at that. TYPO3 logs the response body, so the verified entries end up in the backend log as a diagnosis trail.