Option 1: Disabling Cache

To completely disable the cache for Uniform-related APIs:

1. Open the uniform.server.config.js file in your project.

2. Set the configuration for canvasCache to use no-cache:

module.exports = {
  defaultConsent: true,
  canvasCache: { type: "no-cache" },
};

This configuration ensures that the application fetches fresh data from Uniform with each request, effectively bypassing any cached data.

Option 2: Implementing a Webhook

Alternatively, you can configure a webhook to clear the Next.js cache when content is modified in the Uniform UI.

Implementing the Hook Configuration

1. Open the /app/api/preview/route.ts file.

2. Implement the handler for clearing the cache:

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();

Note that the POST handler in this configuration is responsible for clearing the Next.js cache.

The cache clearing handler covers most of the scenarios of entity updates in Uniform. If you need more advanced cache clearing technique you can implement your own handler.

Configuring the Webhook in Uniform

1. Navigate to Project -> Settings -> Webhook in the Uniform UI.

2. Click Add endpoint

3. Set the Endpoint URL to point to your app's preview route (e.g., https://myapp.com/api/preview?secret=<value from your .env UNIFORM_PREVIEW_SECRET>).

4. Subscribe to the following events to trigger cache clear (note that composition:changed is skipped not to cause extra cache clearing on save.

• CompositionPublished

• CompositionDeleted

• ProjectMapNodeUpdate

• ProjectMapNodeInsert

• ProjectMapNodeDelete

• ManifestPublished

• RedirectInsert

• RedirectUpdate

• RedirectDelete

5. Save the webhook configuration.

This setup ensures that the revalidate function is triggered for composition routes whenever compositions are updated in the Uniform UI. This approach keeps your application cache consistent without requiring a complete bypass of caching.

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.