Core concepts

Developer preview

This feature is in developer preview. Use with caution as it may change unexpectedly. For more information, contact us.

Read this page before you write code with the SDK. It tells you the Uniform terms, and where each term shows up in a Next.js app. For the full product glossary, refer to the composition glossary.

  • Authors build pages in Uniform from the components that you define. They do not write code.
  • Developers write a React component for each component type, and connect the app to Uniform with the SDK.
  • The SDK finds the composition for each URL, and renders it with your React components.

Content model#

A component is a building block of a page, for example a hero, a card or a page. In Uniform, you define the component type in the component library. In your app, you write a React component for each type, and map the two in resolveComponent.

In UniformIn your code
Component type, with a public ID, for example herocomponent.type === "hero" in resolveComponent
Component instanceThe props of your React component (ComponentProps)

For the props, parameters and slots in code, refer to Components and slots in code.

A parameter is a value of a component, for example a title, an image or a link. Authors set the values. Your component gets each value as a ComponentParameter<T> in parameters, and reads it in .value.

const Hero = ({ parameters }: ComponentProps<{ title?: ComponentParameter<string> }>) => ( <h1>{parameters.title?.value}</h1> );

A slot is a named container for child components, for example header, content or footer. The component type defines which components authors can put in each slot. Your component renders a slot with UniformSlot:

<UniformSlot slot={slots.content} />

A composition is a tree of components with one root component. For a website, a composition is usually one page. The root component type is a composition component, for example page. Its slots contain the other components.

A pattern is a reusable part of a composition. Authors can use a component pattern in many compositions. When an author changes the pattern, all compositions that use it change. Canvas shows a pattern alone on the playground route of your app. Refer to Patterns.

Entry#

An entry is structured content of a content type, for example a blog post or a product. A component can show the data of an entry. Refer to Entries.

A composition has a draft state and a published state. Visitors see the published state. Canvas shows the draft state. The SDK uses these numbers:

StateValueUsed for
Published64Visitors
Draft0Preview in Canvas
Editor63Visual editing in Canvas

The project map is the tree of URLs of a project. Each project map node has a path, for example /about, and can have a composition. The SDK uses the Uniform Route API to find the node and the composition for each URL. Refer to Project maps.

In UniformIn your code
A node with a static path, for example /aboutA request to /about renders its composition.
A node with a dynamic segment, for example /products/:slugcontext.dynamicInputs.slug in your components
A redirectThe page sends a redirect.
No node for the pathThe page calls notFound().

The middleware writes the route path and the state of the request into a short string: the code. Then it rewrites the request to app/uniform/[code]/page.tsx. The code contains no visitor data, so all visitors of a published route share one cached page. Refer to How it works.

Uniform Context is the engine that classifies a visitor and chooses the content for the visitor. It runs in the browser, and in edge mode also in the middleware. It uses the Context manifest, which contains the signals, tests and other settings that you publish in Uniform. Refer to Manifest.

TermMeaningIn your code
SignalA rule that adds a score to the visitor when the visitor does something, for example opens a URL with a campaign query string.None. Uniform evaluates it.
ScoreThe value of a visitor dimension, for example interest in a topic.useScores()
QuirkA fact about the visitor, for example the country.useQuirks(), the quirks middleware option
EnrichmentA score from the categories of the content that the visitor views.None. Uniform evaluates it.
ConsentPermission to store the visitor data.defaultConsent in the server configuration

Refer to Signals, Quirks and Enrichments.

FeatureWhat authors doWhat the SDK does
PersonalizationPut a personalization component in a slot, with variants for different visitors.Shows the variants that match the visitor.
A/B testPut a test component in a slot, with variants and a distribution.Gives each visitor one variant, and keeps it.
Visibility rulesAdd rules to a component, for example "show only in Canada".Shows the component in the browser when its rules match.

You do not write code for these features. The SDK renders the $personalization and $test components for you. Refer to Personalization and A/B tests.

Lite modeEdge mode
Who chooses the variantsThe browser, after hydrationThe edge middleware, before the browser gets the page
What the visitor sees firstThe default variantsThe variants of the visitor

Refer to Edge mode execution.

Canvas is the visual editor of Uniform. It shows your app in a preview panel. Authors select components on the page and edit them. Refer to Visual editing.

TermMeaningIn your code
Preview URLThe URL that Canvas opens: /api/preview of your app.app/api/preview/route.ts
Draft modeThe Next.js mode that shows draft content. The preview handler turns it on.draftMode() from next/headers
PlaygroundThe route that shows a pattern alone.app/playground/[code]/page.tsx
Editing markersHTML markers that tell Canvas where each component is. The SDK adds them in the editor state.None

When an author publishes content, Uniform sends a webhook to your app. The SDK revalidates the cached pages that use the content. Refer to Caching.

Last modified
Next
Components and slots in code