Next.js App Router SDK Reference
Developer preview
This feature is in developer preview. Use with caution as it may change unexpectedly. For more information, contact us.
Developer Preview
This reference documents version 20.81.1-alpha.25.sha-f076f9b857. The entry points @uniformdev/next-app-router/edge and @uniformdev/next-app-router/vercel are new in the developer preview.
SDK Reference#
Package requirements#
| Package | Peer dependencies |
|---|---|
@uniformdev/next-app-router | next 16.0.7 or later, react and react-dom 18.2 or 19, @vercel/functions 3 or later (optional) |
@uniformdev/next-app-router-client | next 16.0.7 or later, react and react-dom 18.2 or 19 |
@uniformdev/next-app-router-shared | next 16.0.7 or later, react and react-dom 18.2 or 19 |
All three packages require Node.js 20.9 or later.
@uniformdev/next-app-router#
Server-only exports. The entry point imports server-only.
| Export | Description |
|---|---|
UniformComposition | Resolves the route from a [code] and renders the composition in UniformContext. |
UniformResolvedComposition | Renders the components of a resolver result. Renders nothing for a redirect or a not-found result. |
UniformContext | Starts the browser Context, and adds the visual editing script and the edge state script. Render it one time on each page. |
UniformPlayground | Renders a pattern from a code or a result. Draft mode only. |
resolveRouteFromCode | Resolves the route in a code with the Route API. |
resolveRouteFromPath | Resolves a path with the Route API. |
resolveCompositionById | Gets a composition by ID with the Composition API. |
resolveCompositionBySlug | Gets a composition by slug with the Composition API. |
resolvePlaygroundRoute | Gets the pattern of a playground code. |
requireComposition | Returns the composition, or calls redirect(), permanentRedirect() or notFound(). |
resolveRedirectHref | Returns the target URL of a redirect result. |
deserializePageState | Changes a code into a PageState. |
createUniformStaticParams | Makes the codes for generateStaticParams of the [code] route. |
createUniformPlaygroundStaticParams | Makes the codes for generateStaticParams of the playground route. |
createCompositionCache | Makes a composition cache. |
serverContext | Makes a getter and a setter for a value of one server request. |
findRouteMatch | Matches a path to :name patterns. |
getCompositionDeliveryClient | Composition API client with cache tags. |
getCanvasClient | Deprecated. Use getCompositionDeliveryClient. |
getRouteClient | Route API client with cache tags. |
getProjectMapClient | Project Map API client. |
getManifest / getManifestClient | Context manifest access. |
Types: UniformCompositionProps, UniformResolvedCompositionProps, UniformContextProps, UniformPlaygroundProps, UniformPageParameters, AwaitedUniformPageParameters, PlaygroundParameters, ResolveComponentFunction, ResolveComponentResult, ResolveRouteFunction, ResolveRouteFromCodeOptions, ResolveRouteFromPathOptions, ResolveCompositionByIdOptions, ResolveCompositionBySlugOptions, ResolveRedirectHrefOptions, PageStateSource, ResolvedRouteResult, ResolvedComposition, ResolvedCompositionResult, ResolvedRedirect, ResolvedNotFound, CreateStaticParamsOptions, CompositionCache, CustomRoute, RouteMatch.
@uniformdev/next-app-router/component#
Component utilities for server and client components:
| Export | Description |
|---|---|
UniformSlot | Renders the components of a slot. |
getUniformSlot | Returns the rendered slot items as a ReactNode array. |
UniformText | Renders a text parameter, with in-page editing in Canvas. |
UniformRichText | Renders a rich text parameter. |
useUniformContext | Hook: the browser Context instance. |
useQuirks | Hook: the quirks of the visitor. |
useScores | Hook: the scores of the visitor. |
createClientUniformContext | Makes a browser Context. |
useInitUniformContext | Hook: starts the browser Context. |
Types: ComponentProps, ComponentParameter, ComponentContext, ClientContextComponent, UniformSlotProps, UniformTextProps.
@uniformdev/next-app-router/middleware#
| Export | Description |
|---|---|
uniformMiddleware | Returns a lite mode middleware. |
handleUniformRoute | Handles one request in lite mode. |
resolveUniformRequest | Returns the code, the destination and the headers for a request, for custom middleware. For a playground request, it can return a response. |
determinePreviewMode | Returns "editor", "preview" or undefined from the query strings and draft mode. |
Types: HandleOptions, RewriteOptions, RewriteRequestPathOptions, ResolveUniformRequestOptions, ResolveUniformRequestResult.
@uniformdev/next-app-router/edge#
| Export | Description |
|---|---|
uniformEdgeMiddleware | Returns an edge mode middleware. |
handleUniformEdgeRoute | Handles one request in edge mode. |
UNIFORM_EDGE_ORIGIN_HEADER | "x-uniform-edge-origin", the header of the origin fetch. |
learnedEdgeRouteFilter | Skips the pages that the store recorded without placements. |
createStaticEdgeRouteFilter | Processes only the paths that you list. |
createEdgeRouteStore | Makes a store for edge route records. |
createCachedManifestProvider | Makes a manifest provider that keeps the manifest in memory and in a shared cache. |
Types: UniformEdgeMiddlewareOptions, EdgeRouteFilter, EdgeRouteFilterOptions, CreateStaticEdgeRouteFilterOptions, EdgeRouteStore, EdgeRouteStoreCache, EdgeRouteRecord, EdgeRoutePage, CreateEdgeRouteStoreOptions, RecordedPlacement, RecordedPersonalizationOptions, RecordedTestOptions, ManifestProvider, ManifestProviderOptions, ManifestCache, CreateCachedManifestProviderOptions.
@uniformdev/next-app-router/vercel#
Install @vercel/functions for this entry point.
| Export | Description |
|---|---|
vercelUniformEdgeMiddleware | Returns an edge mode middleware with the Vercel defaults. |
vercelManifestProvider | A manifest provider that uses the Vercel runtime cache. |
vercelEdgeRouteStore | An edge route store that uses the Vercel runtime cache. |
expireVercelRuntimeCacheTags | Expires tags in the Vercel runtime cache. Give it to onRevalidateTags. |
Types: VercelUniformEdgeMiddlewareOptions.
@uniformdev/next-app-router/cache#
The resolvers with 'use cache', for Cache Components: resolveRouteFromCode, resolveRouteFromPath, resolveCompositionById, resolveCompositionBySlug.
@uniformdev/next-app-router/config#
| Export | Description |
|---|---|
withUniformConfig | Wraps the Next.js configuration, and connects uniform.server.config. |
UniformServerConfig | Type of the server configuration. |
@uniformdev/next-app-router/handler#
| Export | Description |
|---|---|
createPreviewGETRouteHandler | GET handler: starts a Canvas preview. Options: resolveFullPath, processPlaygroundPath. |
createPreviewPOSTRouteHandler | POST handler: receives Uniform webhooks. Option: onRevalidateTags. |
createPreviewOPTIONSRouteHandler | OPTIONS handler: answers CORS preflight requests. |
Types: CreatePreviewPOSTRouteHandlerOptions.
@uniformdev/next-app-router/compat#
| Export | Description |
|---|---|
createAdapterResolveComponentFunction | Makes a component resolver for adapted components. |
isAdaptedResolveComponentResultWithType | Returns true for an adapted mapping. |
UniformText | UniformText that takes parameterId. |
Types: ComponentProps, ComponentContext, ResolveComponentResultWithType, AdaptedResolveComponentResultWithType, NonAdaptedResolveComponentResultWithType, UniformTextProps.
@uniformdev/next-app-router-client#
Client-only exports. Use them for a custom client context.
| Export | Description |
|---|---|
createClientUniformContext | Makes a browser Context. |
useInitUniformContext | Hook: starts the browser Context, and updates it on each navigation. |
DefaultUniformClientContext | The default client context component. |
useUniformContext, useQuirks, useScores | The same hooks as in /component. |
EdgePlacement | Renders a personalization or test in edge mode. The SDK uses it. |
Types: ClientContextComponent, ClientContextComponentProps.
@uniformdev/next-app-router-shared#
Types that the other packages use. The other entry points do not export these types.
| Export | Description |
|---|---|
PageState | The values in a code. Refer to PageState. |
CompositionContext | The composition data that each component gets in context. |
SlotDefinition | A slot that each component gets in slots. |
RewriteRequestPathResult | The return value of rewriteRequestPath. |
CacheMode, CanvasCacheMode, ManifestCacheMode, ProjectMapCacheMode | The cache option of the server clients. |
PersonalizeProps, TestProps | Props of the SDK placement components. |
UNIFORM_MIDDLEWARE_QUIRK_COOKIE_NAME | "ufqc", the cookie that sends quirks from the middleware to the browser. |
Install this package with the same version as @uniformdev/next-app-router if you import these types.
@uniformdev/canvas#
| Export | Description |
|---|---|
flattenValues | Gets the values of asset parameters. |
AssetParamValue | Type for asset parameter values |
LinkParamValue | Type for link parameter values. It includes the optional attributes with the custom link attributes of the author. |
RichTextParamValue | Type for rich text parameter values |
@uniformdev/canvas-react#
| Export | Description |
|---|---|
linkParamValueToAnchorProps | Changes a LinkParamValue into React anchor props. It makes the href (with anchors and the mailto: and tel: prefixes), adds the sanitized custom link attributes, and changes class to className. |
@uniformdev/richtext#
| Export | Description |
|---|---|
linkParamValueToHref | Changes a LinkParamValue into an href string. |
linkParamValueToHtmlAttributes | Changes a LinkParamValue into sanitized HTML attributes, for output that is not React. |
Request types#
The behavior of the SDK depends on the type of the request:
| Request | How the SDK finds it | What the middleware does | Composition state | Cached by Next.js | Who chooses the variants | Added for Canvas |
|---|---|---|---|---|---|---|
| Published, lite mode | No draft mode. uniformMiddleware. | Rewrites to /uniform/[code]. | 64 | Yes | The browser, after hydration. The server renders the defaults. | Nothing |
| Published, edge mode, document | No draft mode. An edge middleware. A GET request for an HTML document. | Fetches the cached page with x-uniform-edge-origin: 1, and keeps the variants of the visitor. | 64, with edgeMode | The origin page, yes. The response is private. | The edge middleware | Nothing |
| Published, edge mode, client navigation or prefetch | The rsc or next-router-prefetch header, or Sec-Fetch-Dest: empty | Rewrites only. | 64, with edgeMode | Yes | The browser, before the new page paints | Nothing |
| Published, edge mode, skipped by the filter | The edge route filter answers false. | Rewrites only. | 64 | Yes | The browser, after hydration | Nothing |
| Origin fetch of the edge | The x-uniform-edge-origin header | Nothing. The matcher skips the request. | Same as the code | Yes | The edge middleware, after the fetch | Nothing |
| Draft (preview) | Draft mode is on. | Rewrites to /uniform/[code]. | 0 | No | The browser | The visual editing script |
| Editor (visual editing) | Draft mode is on, and the URL has is_incontext_editing_mode. | Rewrites to /uniform/[code]. | 63, else 0 when there is no editor state | No | The browser | The visual editing script and the editing markers |
| Playground (pattern preview) | Draft mode is on, the path is playgroundPath, and the URL has id. | Rewrites to ${playgroundPath}/[code]. Without id, it answers 400. | 63, else 0 | No | The browser | The visual editing script and the editing markers |
In the draft and editor states, the Route API ignores Uniform redirects. Visibility rules run in the browser for all request types.
Type definitions#
ComponentProps#
type ComponentProps<
TParameters extends Record<string, ComponentParameter> | unknown = Record<string, ComponentParameter>,
TSlotNames extends string = string,
> = {
type: string;
variant: string | undefined;
slots: Record<TSlotNames, SlotDefinition>;
parameters: TParameters;
component: ComponentContext;
context: CompositionContext;
};
ComponentContext#
type ComponentContext = {
_id: string;
_parentId: string | null;
slotName: string | undefined;
slotIndex: number | undefined;
};
CompositionContext#
type CompositionContext = {
_id: string;
type: string;
state: number;
isContextualEditing: boolean;
matchedRoute: string;
dynamicInputs: Record<string, string>;
pageState: PageState;
};
SlotDefinition#
type SlotDefinition = {
name: string;
items: ({
_id: string;
$pzCrit: VariantMatchCriteria | undefined;
variantId: string | undefined;
component: ReactNode;
} | null)[];
};
ComponentParameter#
type ComponentParameter<TValue = unknown> = BaseComponentParameter<TValue> & {
parameterId: string;
_contextualEditing?: { isEditable: boolean };
};
PageState#
type PageState = {
compositionState: number; // 64 published, 0 draft, 63 editor
routePath: string;
keys: Record<string, string> | undefined;
releaseId: string | undefined;
defaultConsent: boolean;
previewMode: "editor" | "preview" | undefined;
locale: string | undefined;
edgeMode?: boolean;
};
The code has the format 3~{state}~{route}~{keys}~{flags}~{releaseId}~{locale}. The SDK removes empty fields at the end. Codes from version 20.81 (2~…) are not supported.
ResolvedRouteResult#
type ResolvedRouteResult =
| { pageState: PageState; route: RouteGetResponseEdgehancedComposition }
| { pageState: PageState; route: RouteGetResponseRedirect }
| { pageState: PageState; route: undefined };
ResolveComponentResult#
type ResolveComponentResult = {
component: ComponentType<ComponentProps<any, any>> | null;
suspense?: {
fallback: ComponentType<any> | undefined;
};
};
UniformServerConfig#
type UniformServerConfig = {
defaultConsent?: boolean;
playgroundPath?: string;
context?: {
disableDevTools?: boolean;
personalizationSelectionAlgorithms?: ContextPlugin["personalizationSelectionAlgorithms"];
};
quirkSerialization?: boolean;
};
HandleOptions#
type HandleOptions = {
rewriteRequestPath?: (options: { url: URL; request: Request }) => Promise<{ path: string; keys?: Record<string, string> } | undefined>;
rewriteDestinationPath?: (options: { source: "route" | "playground"; code: string; pageState: PageState }) => Promise<string>;
queryStrings?: Record<string, string[]>;
release?: { id: string };
quirks?: Quirks;
defaultConsent?: boolean;
locale?: string;
};
UniformEdgeMiddlewareOptions#
type UniformEdgeMiddlewareOptions = HandleOptions & {
manifest: ManifestV2 | ManifestProvider;
onError?: (details: { error: unknown; chunk?: string }) => void;
filter?: EdgeRouteFilter;
store?: EdgeRouteStore;
etags?: boolean;
};
EdgeRouteFilter#
type EdgeRouteFilter = {
shouldProcess: (options: {
pageState: PageState;
waitUntil: (promise: Promise<unknown>) => void;
getRecord: () => Promise<EdgeRouteRecord | undefined>;
}) => boolean | Promise<boolean>;
};
CreateStaticParamsOptions#
type CreateStaticParamsOptions = {
paths: string[];
rewrite?: (options: { path: string }) => Promise<{ path: string; keys?: Record<string, string> } | undefined>;
locale?: string;
edgeMode?: boolean | EdgeRouteFilter | (boolean | EdgeRouteFilter)[];
defaultConsent?: boolean | boolean[];
};
CacheMode#
The cache option of the server clients:
type CacheMode =
| { type: RequestInit["cache"] } // "force-cache", "no-cache", "no-store" and so on
| { type: "revalidate"; interval: number }; // revalidate after the interval, in seconds