Resolve compositions on a page

Task: get a composition on the page yourself, and give it to the renderer.

UniformComposition resolves and renders one composition for the [code] route. Use this recipe when you must do one of these tasks:

• Render more than one composition on a page, for example a page and a shared footer.
• Change the composition data before render.
• Get a composition by its ID or slug, without the project map.
• Render a composition in an ordinary Next.js route, without [code].

The parts#

UniformComposition is these four parts together:

Resolvers#

All resolvers are exported from @uniformdev/next-app-router. @uniformdev/next-app-router/cache exports resolveRouteFromCode, resolveRouteFromPath, resolveCompositionById and resolveCompositionBySlug with 'use cache' for published content. Refer to Caching.

Each resolver must have a page state: the composition state, the locale, the release and the other values of the request. Give the code from the [code] route, or a PageState object. deserializePageState({ code }) changes a code into a PageState.

The result#

• A missing route or composition gives route: undefined.
• An API error also gives route: undefined. The SDK writes the error to the console as a warning.
• In the editor state, the resolver tries the editor state first, and then the draft state. pageState.compositionState tells you which state it found.
• In the published state, the Route API applies Uniform redirects. In other states, it ignores them.

requireComposition#

requireComposition(result) returns a result that always has a composition:

• Redirect: it calls permanentRedirect() for a 301 or 308 redirect, and redirect() for other status codes. Next.js sends a 308 or a 307 redirect.
• Not found: it calls notFound().

resolveRedirectHref({ route, routePath }) gives the target URL of a redirect result, if your code handles the redirects.

UniformResolvedComposition renders nothing for a redirect or a not-found result. Thus you can also skip requireComposition, and render the page without Uniform content when there is no composition.

Render more than one composition#

Render UniformContext one time, and put one UniformResolvedComposition in it for each composition:

UniformContext uses the page state and the composition data of result for the browser Context. Give it the main composition of the page.

Change the composition data before render#

Resolve the composition, change it, and then render it. This replaces the enhanceRoute method of the data client in the stable SDK:

The middleware makes no API calls, so you change the data only on the page.

Use ordinary Next.js routes#

You can render Uniform content in ordinary Next.js routes, for example app/[locale]/[slug]/page.tsx, and not in app/uniform/[code]. This is useful when an app has its pages in Next.js already, and Uniform manages only some regions of them.

The page must then make its own page state, because no code comes from the middleware.

Step 1: Make the page state#

Set defaultConsent to the same value as your server configuration.

Step 2: Resolve and render on the page#

Uniform can have no composition for the path. Then UniformResolvedComposition renders nothing, and the Next.js part of the page still renders. To send a 404 or a Uniform redirect, call requireComposition(result).

Step 3: Configure the middleware and the preview#

• Middleware: rewrite each request to its own URL, so that Next.js uses your route:

  middleware.ts

  import { handleUniformEdgeRoute } from "@uniformdev/next-app-router/edge"; import { vercelManifestProvider } from "@uniformdev/next-app-router/vercel"; import type { NextFetchEvent, NextRequest } from "next/server"; // Make the provider one time, so that it keeps the manifest between requests. const manifest = vercelManifestProvider(); export default function middleware(request: NextRequest, event: NextFetchEvent) { return handleUniformEdgeRoute({ request, waitUntil: (promise) => event.waitUntil(promise), manifest, rewriteDestinationPath: async ({ source }) => source === "route" ? `${request.nextUrl.pathname}${request.nextUrl.search}` : "", // an empty string keeps the default playground rewrite }); } export const config = { matcher: [ { source: "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)", missing: [{ type: "header", key: "x-uniform-edge-origin" }], }, ], runtime: "experimental-edge", };

  CopyCopied!

  The edge middleware fetches your route and keeps the variants of the visitor. Without a filter, it processes all published pages. This agrees with edgeMode: true in getPageState. Do not add a filter, and do not use vercelUniformEdgeMiddleware. A page that the filter skips gets no transform, so its HTML shows all variants until hydration. For lite mode, use handleUniformRoute from @uniformdev/next-app-router/middleware with the same rewriteDestinationPath, and remove edgeMode from getPageState.

• Preview: if your URLs are different from the project map paths, change them in resolveFullPath. Refer to Change the preview path.

• Routes: each project map node that has a composition must have a Next.js route for its path. Without a route, the path gives a 404, also in Canvas preview.

Composition cache#

The composition cache gives components the full ComponentInstance data of the composition. For example, a navigation component can read the parameters of its child components:

Give it to UniformComposition or UniformResolvedComposition:

Then read the data in a component:

Server context#

serverContext keeps a value for one server request. Use it to give data to components deep in the tree without props:

Set the value on the page before the components render. Read it in any server component of the same request. serverContext uses React cache, so it works only in server components.