Using custom query parameters in editing render handlers

Version:

Content SDK's editing render handlers (/api/editing/render) only recognize a fixed set of required query parameters needed to initiate an editing session (sc_itemid, sc_lang, mode, and route). Any additional query parameters present in the request URL are silently ignored and never forwarded to the rendering pipeline.

To explicitly include additional query parameters, you can use the allowedQueryParams configuration option. It gives you explicit control over which custom query parameters are extracted from the incoming request URL and propagated through the editing session, either into Next.js preview data (Pages Router) or into the forwarded render request (App Router).

Examples

The following sections depict the usage of the allowedQueryParams configuration option in Pages Router and App Router apps.

Pages Router

Configure allowedQueryParams in your editing render API route as shown:

// pages/api/editing/render.ts 
import { EditingRenderMiddleware } from '@sitecore-content-sdk/nextjs/editing'; 
 
const handler = new EditingRenderMiddleware({ 
  allowedQueryParams: [ 
    'testParam1',                           // optional by default 
    { name: 'testParam2, required: true },  // required; returns 400 if absent 
    { name: 'testParam3' },                 // optional 
  ], 
}).getHandler(); 
 
export default handler;

App Router

Configure allowedQueryParams when calling createEditingRenderRouteHandlers as shown:

// app/api/editing/render/route.ts 
import { createEditingRenderRouteHandlers } from '@sitecore-content-sdk/nextjs'; 
 
export const { GET, POST } = createEditingRenderRouteHandlers({ 
  allowedQueryParams: [ 
    'testParam1', 
    { name: 'testParam2', required: true }, 
    { name: 'testParam3' }, 
  ], 
});

Using a resolver function

If the parameters you want to allow follow a naming pattern or are only known at runtime, use a resolver function as shown:

allowedQueryParams: (keys) => [ 
  // Allow all parameters that start with 'utm_' (optional) 
  ...keys.filter((k) => k.startsWith('utm_')), 
  // Also require a specific 'testParam1' param 
  { name: 'testParam1' required: true }, 
]

Validation and error handling

When allowedQueryParams is configured, the SDK validates both the standard editing parameters and your custom required parameters before rendering proceeds.

If any parameter marked as required: true is missing from the request, the handler immediately returns an HTTP 400 response with an HTML body listing all missing parameters:

Missing required query parameters: testParam1, sc_itemid

Parameters marked as required: false or configured as plain strings are optional. When absent, they're omitted from the forwarded data without triggering an error.

Reference

The following types are exported from @sitecore-content-sdk/nextjs:

AllowedQueryParam — interface defining an individual allowed parameter
AllowedQueryParams — union type for the full allowedQueryParams config value
AllowedQueryParamsResolver — function type for the dynamic resolver form

The allowedQueryParams option is available on both the Pages Router and App Router editing render handlers.

AllowedQueryParam interface

The interface for the allowedQueryParams option that defines which extra query params to allow. Can be a static array or a resolver function.

interface AllowedQueryParam { 
  name: string;       // The query parameter key to look for 
  required?: boolean; // If true, the handler returns 400 if this param is missing 
}

AllowedQueryParams type

String entries in the array are treated as optional parameters by default.

type AllowedQueryParams = Array<AllowedQueryParam | string> | AllowedQueryParamsResolver;

AllowedQueryParamsResolver type

A resolver function receives the full list of query parameter keys from the incoming request URL and returns the list of parameters to allow. This is useful when the set of allowed parameters is dynamic or prefix-based.

type AllowedQueryParamsResolver = (queryParams: string[]) => Array<AllowedQueryParam | string>;

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