Next.js App Router Cache Revalidation with Uniform SDK

Overview

Uniform provides an out-of-the-box (OOB) cache revalidation handler for projects using the Next.js App Router. This means you do not need to implement custom revalidation logic for Uniform-related content updates—Uniform handles cache invalidation automatically via its provided handler and a next.js tagging mechanism.

This article explains how cache invalidation works in the Uniform SDK for the canvas-next-rsc packages, how tags are generated and applied, and what happens when content changes in Uniform.

Out-of-the-Box Revalidation Handler

For the App Router, Uniform ships with a ready-to-use handler (createPreviewPOSTRouteHandler). This handler processes webhook payloads from Uniform and triggers cache revalidation for affected routes and compositions. You do not need to add extra revalidation logic for Uniform content updates—just use the provided handler.

import { createPreviewGETRouteHandler, createPreviewPOSTRouteHandler, createPreviewOPTIONSRouteHandler, } from '@uniformdev/canvas-next-rsc/handler'; export const GET = createPreviewGETRouteHandler({ playgroundPath: '/playground', resolveFullPath: ({ path }) => (path ? path : '/playground'), }); export const POST = createPreviewPOSTRouteHandler(); export const OPTIONS = createPreviewOPTIONSRouteHandler();

Tagging Mechanism in Uniform SDK

Uniform’s SDK clients for App Router (@uniformdev/canvas-next-rsc) relies on next.js tagging system that enables granular cache invalidation. Tags are attached to fetch requests made by the SDK clients, and these tags are later used to determine which cache entries should be revalidated when content changes.

Tag Generation by Client

Composition (canvasClient):

Adds tags with the prefix composition: followed by the composition ID.

Example for compositionId 12345678:

composition:12345678

Route (routeClient):

Adds tags with the prefix path: for each segment of the requested path, as well as a general route tag.

Example for /shop/category/TV-1234:

route path: path:/shop path:/shop/category path:/shop/category/TV-1234

The route tag is used to revalidate all Uniform-related fetches, especially when a pattern composition is updated.

Manifest and Project Map Clients:

Add tags such as manifest as appropriate for their data.

How Revalidation Works

When Uniform content is updated (e.g., a composition is changed or a project map node is updated), the webhook handler receives a payload describing the change. The handler then determines which tags and paths are affected and triggers revalidation for those cache entries.

Example: Dynamic Routes

Suppose you have a dynamic route in Uniform:

Uniform Project Map Node: /shop/category/:product

Fetched Paths:

/shop/category/TV-1234
/shop/category/TV-4321

For each fetch, the following tags are generated:

route
path:
path:/shop
path:/shop/category
path:/shop/category/TV-1234 (or path:/shop/category/TV-4321)

When a composition or route is updated:

If the update is to a pattern composition (which can be reused in many places), the handler revalidates the general route tag, ensuring all related fetches are invalidated.
For other updates, the handler builds the path tags up to the first dynamic segment and revalidates those. For example, if /shop/category/:product changes, the handler will revalidate path:/shop/category, which covers all children under that category.

Note: This article applies to the Next.js App Router and the Uniform canvas-next-rsc SDK. For the Page Router, refer to the corresponding documentation.