Using the proxy execution context

Version:

You can inspect the execution result of each proxy in your Next.js middleware by passing a ProxiesContext map to defineProxy().exec(). Use the context to log proxy outcomes, debug middleware behaviour, or make downstream decisions based on proxy execution results.

The proxiesContext parameter is optional. Existing middleware implementations that do not pass a context map continue to work unchanged.

Note

The proxy execution context is only available in Content SDK 2.2 or later.

Proxy execution context types

A new types.ts file defines the core data structures for the context feature:

Type	Structure
`ProxiesContext`	`Map<string, ProxiesContextMapValue>` passed through all proxies, keyed by proxy name.
`SuccessfulProxyExecution`	`{ executedSuccessfully: true, error: null }`, extended per-proxy with richer data.
`FailedProxyExecution`	`{ executedSuccessfully: false, error: unknown }`
`ProxiesContextMapValue`	A union type of `SuccessfulProxyExecution` and `FailedProxyExecution`

Available result types per proxy

The following result types are available per proxy:

SuccessfulBotTrackingProxyExecution — includes botDetected
SuccessfulLocaleProxyExecution — includes locale and rewrote
SuccessfulMultisiteProxyExecution — includes siteName, rewritePath, isSitecorePreview
SuccessfulPersonalizeProxyExecution — includes identifiedVariantIds and rewritePath
SuccessfulPreviewProxyExecution — includes pageDataReceived
SuccessfulRedirectsProxyExecution — includes requestUrl, redirectUrl, redirectStatus, isExternal

All types are exported from @sitecore-content-sdk/nextjs.

Proxy implementation changes

Proxy implementations must now:

Expose a name: string property, which is used as the key in the context map.
Accept an optional proxiesContext?: ProxiesContext parameter in the handle() method.

The defineProxy().exec() function forwards the context to each proxy in the execution chain.

After execution, each proxy writes its result into the shared ProxiesContext map using its name as the key. Successful executions use a proxy-specific success type. Failed executions use the shared FailedProxyExecution type.

To check execution results, use the generic isSuccessfulProxyExecution type guard to determine whether a proxy execution result is successful. If the result is successful, you can safely access proxy-specific fields. Otherwise, inspect the error field.

Using the proxy execution context

The following example shows how to pass a context map to the proxy chain, retrieve a proxy execution result using its name, safely narrow the result using a type guard, and handle both successful and failed executions.

const proxiesContext: ProxiesContext = new Map();

const response = await defineProxy(
  preview,
  botTracking,
  multisite,
  redirects,
  personalize
).exec(req, undefined, proxiesContext);

const redirectsInfo = proxiesContext.get(redirects.name);

if (isSuccessfulProxyExecution<SuccessfulRedirectsProxyExecution>(redirectsInfo)) {
  console.log('Redirects proxy result:', redirectsInfo);
} else {
  console.log('Redirects proxy failed:', redirectsInfo?.error);
}

return response;

If you have suggestions for improving this article, let us know!