---
title: "On-demand static revalidation for App Router apps"
slug: "on-demand-static-revalidation-for-app-router-apps"
abstract: "How on-demand static revalidation (OSR) allows published Sitecore content to refresh in your Next.js App Router application."
---
# On-demand static revalidation for App Router apps

On-demand static revalidation (OSR) allows published Sitecore content to refresh in your Next.js App Router application without requiring a full redeploy. OSR uses Next.js tag-based cache invalidation (`revalidateTag`) and requires cached content to be tagged using Cache Components (`'use cache'` and `cacheTag()`). In Content SDK, this wiring is provided out of the box by the `nextjs-app-router-cache-components` template.

OSR is optional. You can use [Cache Components](https://nextjs.org/docs/app/getting-started/caching) with time-based expiration only, with tag-based revalidation, or fetch content dynamically without caching. The revalidation endpoint only invalidates existing tagged cache entries. If content is not cached with matching tags, revalidation requests have no effect.

The Content SDK now ships two App Router starter templates:

- **nextjs-app-router** - the standard template where you can choose your own caching strategy. Cache Components and OSR are not configured by default.
- **nextjs-app-router-cache-components** - the standard template with Cache Components enabled, Sitecore cache helpers preconfigured with cache tags, and a revalidation route handler out of the box.

Both templates share the same routing (`[site]/[locale]/[[...path]]`), middleware, `SitecoreClient`, preview/editing, and i18n support.

> [!note]
> Preview and editing always remain dynamic as they call `SitecoreClient` directly and are never cached. OSR is available only in Content SDK 2.2 or later.

## Choosing a caching strategy

You can choose a caching strategy based on your requirements. Listed below are some of the common scenarios:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Requirement</p></th><th class="th"><p>Approach</p></th></tr></thead><tbody><tr><td class="td"><p>Content updates within minutes or hours</p></td><td class="td"><p>Use Cache Compnents with a <a class="link" href="https://nextjs.org/docs/app/api-reference/functions/cacheLife" target="_blank" rel="noopener"><code class="code">cacheLife</code></a> profile. No webhook is needed</p></td></tr><tr><td class="td"><p>Content must appear immediately after publish</p></td><td class="td"><p>Wire a Sitecore webhook to POST <code class="code">/api/revalidate</code>.</p></td></tr><tr><td class="td"><p>Invalidation based on an operation or selection</p></td><td class="td"><p>Call the endpoint manually with a <code class="code">tags[]</code> payload</p></td></tr><tr><td class="td"><p>No caching for published content</p></td><td class="td"><p>Skip Cache Component helpers entirely and fetch content dynamically via <code class="code">SitecoreClient</code></p></td></tr></tbody></table>

> [!important]
> Webhook-based OSR requires both:
>
> -   Cache Components enabled, and
>
> -   Cached content tagged with the same `sc:*` tags that the revalidation endpoint invalidates.
>
>
> The Content SDK provides this configuration through the cache helpers included in the `nextjs-app-router-cache-components` template.

## Template contents

The cache-components template includes the following out of the box:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Area</p></th><th class="th"><p>Behavior</p></th></tr></thead><tbody><tr><td class="td"><p>Cache Components</p></td><td class="td"><p>Enabled in <code class="code">next.config.ts</code></p></td></tr><tr><td class="td"><p>Cached reads</p></td><td class="td"><p><code class="code">getSitecorePage</code>, <code class="code">getSitecoreDictionary</code>, <code class="code">getSitecoreErrorPage</code> in <code class="code">src/lib/cache/</code></p></td></tr><tr><td class="td"><p>Revalidation route</p></td><td class="td"><p>Exposed as POST <code class="code">/api/revalidate</code> via <code class="code">createSitecoreRevalidateRouteHandler</code></p></td></tr><tr><td class="td"><p>Dictionary caching</p></td><td class="td"><p>SDK in-process dictionary cache disabled in <code class="code">sitecore.config.ts</code>; invalidation flows through Cache Components only</p></td></tr></tbody></table>

## Flow of OSR

On-demand static revalidation happens in three phases:

1. Read path - When a visitor first requests a page, the `getSitecorePage` or `getSitecoreDictionary` fetches data from Sitecore and stores the result in Next.js's built-in data cache attaching `sc:*` tags to the results.
2. Invalidation path - After a publish, Sitecore fires a webhook that POSTs to `/api/revalidate`. The handler, [`createSitecoreRevalidateRouteHandler`](https://github.com/Sitecore/content-sdk/blob/dev/ref-docs/nextjs/route-handler/functions/createSitecoreRevalidateRouteHandler.md), reads the publish payload, resolves which `sc:*` tags correspond to the updated items, and calls Next.js's native [`revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag) for each one. The handler only invalidates cache entries that were previously created with matching `sc:*` tags. This tagging is provided by the cache helper functions in `src/lib/cache`.
3. Next request - Affected cache entries are marked as stale. This is not served to the next visitor and the page fetches fresh data from Sitecore using `getSitecorePage` or `getSitecoreDictionary` again. If no matching tags exist in the Next.js cache, the revalidation request completes successfully but no cached content is invalidated.

## Cache tag helpers

The SDK computes tags via public helpers. Cached reads and revalidation share the same tags:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Tag</p></th><th class="th"><p>Purpose</p></th><th class="th"><p>Example</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">sc:route:{site}:{locale}:{path}</code></p></td><td class="td"><p>URL-level</p></td><td class="td"><p><code class="code">sc:route:default:en:about</code></p></td></tr><tr><td class="td"><p><code class="code">sc:item:{id}:{locale}:{version}</code></p></td><td class="td"><p>Item-level</p></td><td class="td"><p><code class="code">sc:item:71b0ba07…:en:latest</code></p></td></tr><tr><td class="td"><p><code class="code">sc:dict:{site}:{locale}</code></p></td><td class="td"><p>Dictionary</p></td><td class="td"><p><code class="code">sc:dict:default:en</code></p></td></tr></tbody></table>

- **Pages** - `getSitecorePage` attaches route and item tags via `collectSitecorePageCacheTags`.
- **Dictionary** - `getSitecoreDictionary` attaches a dictionary tag via `buildSitecoreDictionaryCacheTag`.
- **Personalization** - Variant pages are isolated by URL path. When `PersonalizeProxy` identifies a variant, it rewrites the request to an internal path encoding the variant ID (for example, `/default/en/about/_variantId_hero-b`). Each unique path gets its own cache entry, so variants never overwrite each other. The `sc:route:…` tag attached always uses the clean URL (variant segments are stripped), while the `sc:item:…` tag is shared across all variants of the same page item. This means a publish webhook invalidating `sc:item:{pageItemId}:en:latest` clears all variant cache entries for that page at once. For component A/B testing with multiple simultaneous experiments, each variant combination produces a distinct cached response, all of which are invalidated together via the shared item tag. To invalidate a single specific variant URL explicitly, send its full `sc:route:…` tag in the `tags[]` payload

There is currently no cache tag per variant. Invalidating either the shared `sc:item:…` tag (typical publish webhook) or the `sc:route:…` tag (normalized path, variant segments stripped) clears all variant cache entries for that page. The variants are isolated when stored. But when it comes to clearing the cache, you can't pick and choose which ones to invalidate.

> [!note]
> Publish webhooks typically invalidate item tags. Route tags are only cleared when the full `sc:route:…` string is explicitly sent in a revalidate request.

## Revalidation endpoint

The Content SDK exposes `createSitecoreRevalidateRouteHandler` from `@sitecorecontent-sdk/nextjs/route-handler`. It is a factory that returns a Next.js App Router POST handler. You can mount it to any route, the cache-components template wires it at POST `/api/revalidate` via `src/app/api/revalidate/route.ts`. The handler accepts an object of [`SitecoreRevalidateRouteHandlerOptions`](https://github.com/Sitecore/content-sdk/blob/dev/ref-docs/nextjs/route-handler/type-aliases/SitecoreRevalidateRouteHandlerOptions.md).

The following are the parameters required by the revalidation endpoint:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Parameter</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">secret</code></p></td><td class="td"><p>String</p><p>Default: <code class="code">undefined</code></p></td><td class="td"><p>Shared secret for POST <code class="code">/api/revalidate</code>. If omitted here, the handler falls back to <code class="code">process.env.SITECORE_REVALIDATE_SECRET</code>. When a non-empty value is set (via this option or env), callers must pass it in the <code class="code">x-revalidate-secret</code> request header.</p></td></tr><tr><td class="td"><p><code class="code">defaultLocale</code></p></td><td class="td"><p>String</p><p>Default: <code class="code">'en'</code></p></td><td class="td"><p>Locale used for item tags when culture is missing, and for dictionary tags when a site has no language configured.</p></td></tr><tr><td class="td"><p><code class="code">cacheProfile</code></p></td><td class="td"><p><code class="code">RevalidateTagCacheProfile</code></p><p>Default: <code class="code">"max"</code> (recommended)</p></td><td class="td"><p>Next.js <code class="code">revalidateTag</code> cache profile (second argument). Accepts a string matching a <code class="code">cacheLife</code> profile in <code class="code">next.config</code>, or an object with <code class="code">{ expire }</code> per Next.js docs.</p></td></tr><tr><td class="td"><p><code class="code">sites</code></p></td><td class="td"><p><code class="code">SiteInfo[]</code></p><p>Default: <code class="code">undefined</code></p></td><td class="td"><p>List of sites (for example, from <code class="code">.sitecore/sites.json</code>). Adds one <code class="code">sc:dict:&lt;site&gt;:&lt;locale&gt;</code> tag per site on every revalidation call. <code class="code">generateSites</code> always includes the configured default site.</p></td></tr></tbody></table>

> [!important]
> The `createSitecoreRevalidateRouteHandler` only calls Next.js `revalidateTag()` for resolved `sc:*` cache tags. For revalidation to refresh published content, those same tags must already be attached to cached responses using Cache Components and `cacheTag()`. The cache-components starter template provides this implementation through `getSitecorePage`, `getSitecoreDictionary`, and `getSitecoreErrorPage`.

### Flow of revalidation

There are two ways in which revalidation can occur:

1. The primary flow is using a Sitecore webhook. Point your Experience Edge/Content Operations webhook at your app URL. The handler processes the standard payload:
    - `updates[]` — Each publish row's identifier (with `-media`/`-layout` stripped) is mapped to `sc:item:{id}:{locale}:latest`. Locale is derived from `entity_culture`, or falls back to the app's default language.
    - Dictionary tags - One `sc:dict:{site}:{locale}` tag per site from `.sitecore/sites.json` is revalidated on every call.
2. You can also revalidate without webhooks using a `tags` payload that the endpoint accepts.

    ```json
    { "tags": ["sc:route:default:en:about", "sc:item:…"] }
    ```

    <table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>tags[] value</p></th><th class="th"><p>Behavior</p></th></tr></thead><tbody><tr><td class="td"><p>Starts with <code class="code">sc:</code></p></td><td class="td"><p>Revalidated as-is</p></td></tr><tr><td class="td"><p>Bare item ID</p></td><td class="td"><p>Mapped to <code class="code">sc:item:{id}:{defaultLocale}:latest</code></p></td></tr></tbody></table>