Uniform

View saved version →

---
name: uniform-assets
description: >-
  Working with Uniform image/media assets end to end — defining an `asset`
  parameter, rendering an image `src` with `imageFrom` (the graceful,
  future-proof default), reading other fields off the raw asset item, the stored
  asset-value shape, DAM library assets vs external `custom-url` assets,
  seeding/migrating asset values in compositions, and the traps around parameter
  type transitions. Use when a component needs an image/photo/video from Uniform,
  when converting a `text` URL field to an `asset` field, when you want
  responsive/transformed images with focal points.
---

# Uniform assets

How to model, render, and author image/media assets in this Uniform.

## 1. Choose the parameter type deliberately

| Use | When |
|-----|------|
| `asset` parameter | Real content authors will pick/manage the image; you want the Canvas asset picker, DAM library, and image CDN/transforms. **Default for authored imagery.** |
| `text` parameter (URL) | Quick/pragmatic cases, throwaway/demo data, or an image URL that's genuinely just a string the author pastes. Simpler, but no picker, no metadata, no CDN transforms. |

Don't reach for `text` just to avoid the asset plumbing — the plumbing is small
(below). Reach for `text` only when a bare URL really is the right model and a text input is the right editor experience.

## 2. Define an asset parameter

In the component definition. Via MCP `mutateComponent` or `uniform-data/component/<type>.json`:

```json
{
  "id": "photo",
  "name": "Photo",
  "type": "asset",
  "typeConfig": { "allowedTypes": ["image"] },
  "guidance": "A square headshot image. If empty the card shows initials."
}
```

- `typeConfig.allowedTypes` ∈ `["image", "video", "audio", "other"]` (one or more).
- The parameter `id` must match the key you destructure in the `.tsx`.

## 3. Render an image `src` — `imageFrom` (the default)

**Default to `imageFrom` for turning an asset parameter into an img `src`.**
It is the most future-proof choice:

- Accepts a **raw asset item OR a bare URL string**, so it keeps working if the
  parameter's source ever changes (DAM ⇄ `custom-url` ⇄ external).
- **No-ops transforms** for non-image assets and anything outside the Uniform
  Asset Library — external / other-DAM URLs pass through unchanged, so one code
  path is correct for every source.
- **Auto-applies the asset's focal point** plus your resize/fit *when the image is
  a Uniform DAM asset*. Those features "just start working" after a move to the
  DAM, with **no code change**.

Use the `imageFrom` and `AssetParamValue` from `@uniformdev/assets`

```ts
import { imageFrom, type AssetParamValue } from "@uniformdev/assets";
```

### For use with a `ComponentParameter<AssetParamValue>`

When the parameter type you are working with is `ComponentParameter<AssetParamValue>`, first access the `.value`. It is an `AssetParamValue`, which is an array of `AssetParamValueItem`.

```tsx
// photo?: ComponentParameter<AssetParamValue>
const item = photo?.value?.[0];
```

### Build an img from a single `AssetParamValueItem`

Once you have a single item, build an img src and attributes from the `AssetParamValueItem` that `imageFrom` needs.

```tsx
const src = item
  ? imageFrom(item)
      .transform({ width: 192, height: 192, fit: "cover" })
      .url()
  : undefined;

if (!src) return null;
return <img src={src} alt={item?.fields.title?.value ?? ""} width={192} height={192} />;
```

Safety rules:

- **Give `imageFrom` a single item or a string — never the array.**
  `imageFrom([item])` returns `""` (empty), not the URL. Use `value[0]`.
- **Guard `undefined`/`null`.** `imageFrom(undefined)` / `imageFrom(null)`
  **throw** (`Cannot read properties … (reading 'fields')`). The `photo?.value?.[0]
  ? … : undefined` shape guards this; `imageFrom({}).url()` returns `""`.

`transform` options (`ImageFromTransformProps`): `width?`, `height?`,
`fit?: 'scale-down' | 'contain' | 'cover'`; and for `fit: 'cover'` also

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: uniform-automations
description: >-
  Uniform Automations (`defineAutomation`, `defineScoutAutomation`, `ScoutClient`, `*.automation.ts`). Use when handling a Uniform content event, a schedule, an inbound webhook, an `aiTool`, a Scout workflow-stage job, a Uniform sync with an external system, or reviewing a `*.automation.ts` module.
license: MIT
---

# Uniform automations

Serverless functions authored in the user's repo and deployed with the Uniform CLI. This skill is the judgement the SDK types don't give you. Product surface: [automations guide](https://docs.uniform.app/docs/guides/automations). Signatures: JSDoc in `@uniformdev/automations-sdk` and `@uniformdev/canvas`.

## Mental model

One automation is one TypeScript module that default-exports the result of a define function. Everything else it imports is just modules.

| | `defineAutomation({ metadata, handler })` | `defineScoutAutomation(metadata, instructions)` |
|---|---|---|
| You write | code | natural-language instructions |
| The actions are | whatever your handler does | the tool calls the Scout agent makes |
| Runs as | your bundled code, in Uniform's sandbox | Uniform's Scout agent, headlessly |
| `permissions` | optional | required — the agent has no authority without a role |
| Cost | compute only | consumes AI credits per run |

Both live in `*.automation.ts`; the CLI infers which from the default export. The public ID is the filename: `send-welcome.automation.ts` deploys as `send-welcome`. Renaming orphans the deployed automation; deleting the old one is a separate `uniform automation delete`.

## Decision procedure

State, in order, before opening any file: Kind (`handler` | `scout` | `hybrid`), Binding (`stage <id>` | `event <name>` | `none`), Triggers (the array), Filter (the CEL, or `none`), Identity (`role <name from the user>` | `none`).

**1. Kind.** Handler for deterministic work. Reach for AI only where the task is judgement-shaped. `defineScoutAutomation` when the whole job is agentic; `defineAutomation` plus `ScoutClient` when you need control around one AI step. [Code automations](https://docs.uniform.app/docs/guides/automations/code-automations) are this skill's path.

**2. Binding.** Work *to* content binds to a `workflow.transition` on a stage the automation owns. A save is not a binding. One owning automation per auto-transitioning stage. [workflows](https://docs.uniform.app/docs/guides/composition/workflows).

**3. Triggers.** Always an array. Events, `schedule`, and `incomingWebhook` compose and reduce to one `eventType`-discriminated `input` union. `aiTool` is exclusive — it runs as the invoking caller. At most one `schedule`, at most one `incomingWebhook`, no duplicate event names. Event names and payloads: `@uniformdev/webhooks`, [webhooks](https://docs.uniform.app/docs/guides/webhooks), [event catalog](https://www.svix.com/event-types/us/org_2HgMLYs57QWpjfM80UPmW98qTgT/).

**4. Filter.** Cheap predicates go in the CEL `filter`; keep filters total (only fields the payload schema guarantees). Expensive predicates and authenticity checks stay in the handler. A miss records no run. [filtering](https://docs.uniform.app/docs/guides/automations/triggers#filtering).

**5. Identity.** No `permissions` means no Uniform API access. Role names are not discoverable: ask the user which role to grant, or to create one. They can only grant roles they hold; automations cannot run as a team admin. [the automation identity](https://docs.uniform.app/docs/guides/automations/code-automations#the-automation-identity).

When Kind is `scout` or `hybrid`, read [references/scout.md](references/scout.md). Then read [references/best-practices.md](references/best-practices.md) — workflow-stage, filters, outcomes, delivery, limits, and webhook auth if Triggers includes `incomingWebhook`.

Then write:

6. Module shape: [references/sdk-api.md](references/sdk-api.md). Copy a [template](templates/) when the types don't lead you there — stage (`on-workflow-

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

View saved version →

---
name: uniform-content-modeling
description: Best practices for content modeling in Uniform — designing content types with well-chosen fields, validations, and naming, deciding what belongs in structured content vs the experience layer, modeling content classification (categories, tags, taxonomies), modeling relationships between entries with references, designing content for discoverability across search and answer engines and multi-channel delivery, and organizing entries for reuse and localization. Use when creating or updating Uniform content types or entries, migrating structured content from another CMS into Uniform, or reviewing an existing content model for best-practice violations.
license: MIT
---

# Uniform content modeling

Content modeling defines display-agnostic content types and the entries created from them. Experience modeling defines how content is displayed and composed via component definitions and patterns. Keep the two separate: this skill is about building content models that are reusable across presentations and channels.

## Key principles

### Model content, not presentation

Display concerns (layout, styling, variants) belong in component definitions and patterns, not content types.

### Model classification once, deliberately

Classify with select fields or references to a classification content type — never free text. Pick one mechanism per classification and reuse it across types.

### Model for findability

Fields you filter or sort on must use filterable field types. Blocks, asset, image URL, JSON, and link fields cannot be filtered by the Edge Delivery API — decide query requirements before choosing field types.

### Borrow from Schema.org

Use Schema.org types as field checklists, model explicit fields, and let the frontend serialize JSON-LD. Only store raw JSON-LD when a Mesh integration or AI agent like Scout computes it.

## Gotchas

Uniform facts that defy reasonable assumptions — know these before changing a model:

- **Field public IDs are immutable after creation.** A rename means a new field plus content migration, so decide IDs deliberately and keep them consistent across types.
- **A reference field's single/multi choice cannot be changed after setup.** Default to a multi reference with plural naming and a `max: 1` validation; relaxing a max later is a validation change, switching single → multi is a re-model.
- **Filtering on a reference field matches only the referenced entry's id, slug, and name** — never its custom fields. Slugs on referenced types are the filter key.
- **Block fields cannot be filtered and cannot be marked overridable in entry patterns.** Keep queryable or per-entry-variable data out of blocks.
- **The native entry slug field is not localizable.** Localized URL paths need a custom localizable text field driving routing.
- **Changing or removing a select option value does not update existing entries.** Treat vocabulary changes as content migrations.

## Resources

Read the reference file for the task at hand:
- [Content types](references/content-types.md) — read when creating or updating a content type or block type: naming, public IDs, slugs, display name, validation philosophy, field-level AI guidance
- [Entries](references/entries.md) — read when organizing entries at scale, choosing a reuse mechanism (reference vs block vs entry pattern), using entry patterns, or planning localization
- [Relationships](references/relationships.md) — read before adding a reference field or designing shared types (Author, Brand, Category): reference vs embed, cardinality, graph hygiene, publishing behavior
- [Content classification](references/content-classification.md) — read when modeling categories, tags, or taxonomies: select vs reference decision, hierarchies, anti-patterns, enrichments vs content classification
- [SEO and multi-channel](references/seo-and-multichannel.md) — read when modeling SEO/OpenGraph fields, structured data, or content for answer engines and non

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

View saved version →

---
name: uniform-enrichment-recommendations
description: >-
  Add personalized, relevance-ranked content recommendations to a Uniform +
  React/Next.js project by boosting Content API results with Uniform Context
  enrichment scores. Use when a user wants visitor-personalized recommendations,
  dynamic product/article/promotion lists ranked by interest, enrichment-based
  content ranking, or mentions enrichment boosting, boost orderBy, or the `ufvd`
  cookie with Uniform.
license: MIT
---

# Uniform Enrichment-Boosted Recommendations

Add a feature that re-ranks a Uniform Content API query by the current visitor's
**enrichment scores** (their interest profile from Uniform Context), so each
visitor sees the same content pool ordered by what is most relevant to them.
Works for any content type (products, articles, promotions, events, ...).

## How it works (read first)

1. Uniform Context accumulates visitor **enrichment scores** in the `ufvd`
   cookie, keyed `<categoryId>_<value>` → number (e.g. `int_internet: 50`).
2. On the server, those scores are converted into a Content API **boost clause**
   passed to `orderBy`: `boost|fields.<field>:<value>:<weight>`.
3. `EntryDeliveryClient.list({ orderBy: [clause] })` re-ranks the result set.
4. No scores → no clause → graceful fallback to default ordering.

**Critical alignment rule:** the enrichment value's suffix (after the first
`_`) must equal the value stored in the content field you boost on. Enrichment
`int_internet` only boosts entries whose target field holds `internet`. If they
don't match, nothing re-ranks. Validate this before writing code.

For the full conceptual reference, terminology, and troubleshooting, read
[references/reference.md](references/reference.md).

## Prerequisites — verify before implementing

Stop and confirm each. If one is missing, set it up or tell the user it's
required first.

- [ ] **Uniform Context available.** `@uniformdev/context` provides the scoring
      engine. In Next.js App Router it ships bundled with
      `@uniformdev/next-app-router` and the tracker/provider is wired by the SDK
      (e.g. `UniformComposition` + `clientContextComponent`), so a separate
      `@uniformdev/context` install or hand-rolled `<UniformContext>` is **not**
      required — do not flag the feature as broken just because you can't find one.
      The server-side boost reads the `ufvd` cookie directly and falls back to
      default ordering when no scores are present, so the component works
      regardless. (Live per-visitor re-ranking still needs scores to actually
      accumulate — see the score-growth note below.)
- [ ] **Content client deps available** (`@uniformdev/canvas`).
- [ ] **API key + project ID** in env (commonly `UNIFORM_API_KEY`,
      `UNIFORM_PROJECT_ID`) with read-entries permission.
- [ ] **A target content type** exists with a field whose values can match
      enrichment value suffixes (the alignment rule above).
- [ ] Detect the framework (Next.js App Router vs Pages vs other React). The
      cookie read differs; templates assume Next.js App Router (`cookies()` from
      `next/headers`). Adapt for other setups.

## Workflow

Copy this checklist and track progress:

```
- [ ] Step 1: Confirm prerequisites + detect framework/conventions
- [ ] Step 2: Confirm enrichment categories + content field alignment in Uniform
- [ ] Step 3: Add the three frontend layers (helpers, score reader, fetch)
- [ ] Step 4: Build/render the component (async server component or Suspense)
- [ ] Step 5: Register the Uniform component definition + component pattern (MCP)
- [ ] Step 6: Wire boostEnrichments param, then verify re-ranking
```

### Step 1 — Confirm prerequisites and conventions

Run the prerequisite checklist. Inspect the repo to match its conventions:
where utilities live (e.g. `src/utils`), how Uniform components are registered
(the component resolver/mapping), and the cookie/SSR approach. Reuse existing
patterns; do not introduce a new struct

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: uniform-experience-modeling
description: Best practices for experience modeling in Uniform — designing component definitions with well-chosen parameters, slots, editors, and naming, deciding between slots and parameters, blocks and slots, content-agnostic and content-specific components, choosing component granularity (atomic building blocks vs pre-composed components), and using component and composition patterns well (overrides, pattern data resources, slot sections, localization). Use when creating or updating Uniform component definitions or patterns, mapping code components (React, etc.) or a design system to Uniform components, or reviewing an existing component library for best-practice violations.
license: MIT
---

# Uniform experience modeling

Experience modeling is the process of building Uniform component definitions that represent the experience layer of a digital product: how content is displayed and how authors compose it. It contrasts with content modeling, which defines display-agnostic structured content (content types and entries). This skill encodes best practices for building component sets that are easy to author, easy to maintain, and map cleanly to code components.

## Key principles

### Components map to code components

A Uniform component typically maps to a frontend code component. Parameters map to props; slots map to children or child-component props. Not every prop needs to be exposed — hardcode props that editors should not manage. Align parameter public IDs and types with the corresponding props to avoid mapping logic.

### Choose the right component granularity

Components correlate strongly to the design system rendering the experience, and atomic design is a useful lens: atoms and molecules map to component definitions (or parameters — not every design-system component needs a Uniform component), organisms to definitions plus component patterns, templates to composition patterns, pages to compositions. Balance granular atomic and layout components (flexible, but shifts design decisions, design consistency, and responsive handling to editors) against pre-composed components and patterns (easier, more guard rails); both can coexist, with granular components reserved for exceptions and experimentation.

### Design for editors first

Names, help text, grouping, and editor controls exist for non-technical authors. Use non-technical names, write help text only when the purpose isn't obvious, group related parameters, collapse advanced settings, and pick the editor control (radio, segmented control, slider, switch, checkboxes) that matches how authors think about the setting.

### Restrict slots deliberately

Never enable the allow-all-components toggle on a slot. Allow only the components and patterns that make sense, plus the built-in Personalization and A/B Test components where optimization is expected, and the Loop component where children are rendered dynamically from data. An explicit allow-list may still be wide for granular setups — what to avoid is the allow-all toggle, not a long list.

### Prefer slots over parameter groups and blocks for nested UI

Slots keep nested elements flexible: extensible, personalizable, A/B testable, and reusable via patterns. Use parameter groups when simplicity matters more, and blocks only for non-visual structured data. When requirements are unclear, default to a restricted slot.

### Keep composition parameters for global page data

Reserve composition parameters for global, page-level data (e.g. SEO/OpenGraph metadata); experience content belongs in components in the composition's content slot.

### Keep components content-agnostic

Prefer "Card" over "Recipe Card" — the component is a display container. Create content-specific variations with component patterns — either static (fixed, reused content) or connected to a data resource that wires entry fields to the base component's parameters. Only create content-specific components for core dom

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: uniform-forms
description: >-
  Use when adding a form (like contact, signup, newsletter, lead-capture or survey) to a
  Uniform project, when creating form field component definitions or building a generic form submission endpoint.
  Do not use when embedding an iframe for an external form provider.
license: MIT
---

# Uniform forms

A form in Uniform is not a special entity — it is a **composition of components**. A `Form` container component renders the `<form>` element and owns the resulting submit action; each input is its own component placed in the container's slot. Authors assemble forms in Uniform's visual editor; developers own the markup, state, and submission.

## Architecture

```
form                       container: renders <form>, owns state, submits
├── slot: formFields       formTextField, formTextAreaField, formSelectField,
│                          formCheckboxField, formRadioField (+ $personalization, $test)
└── slot: formButtons      formButton (min 1) (+ $personalization, $test)

formSelectField / formRadioField
└── slot: options          formSelectOption, formRadioOption (+ $personalization, $test)
```

Field components **self-register** with that context on mount and read/write their own value through it. The container never inspects its slot contents.

## Author-set Field name and identifier

**Every field must have a stable, author-set identifier.** The `name` parameter is required on every field component. Slugify it to get the identifier used for the HTML `name`/`id`, and the payload key. **Never fall back to a generated identifier, warn in the Uniform's visual editor when a field is missing an identifier**.

## Form Submit or Fields should self-register

**Do not introspect slots.** Do not walk `component.slots.formFields` to build fields. That code can easily miss fields nested inside `$personalization` or `$test` wrappers, and duplicates the slot's structure in two places. Use the form submit event to gather the data or self-register each field based on the component's nested context.

## Options are a slot, not a `$block` parameter

Dropdown and radio options are components in an `options` slot. This is good practice for these components as it allows them to be personalized, be A/B tested, or support visibility conditions. Do not use blocks or a `$block` parameter as **it cannot be created or edited via MCP or AI**, so a block-based model cannot be built or maintained by an agent.

## Restrict every slot explicitly

**Never set `allowAllComponents: true`.** List the field components, and add `$personalization` and `$test` to `formFields` so individual fields can be optimized.

## Always validate on the server

Client-side validation, `required`, `minlength`, `maxlength`, `pattern` and other built-in form input parameters drive the HTML validation UX only. Re-check every required field in the API route.

## Keep track of the form submit state

Track `idle | submitting | success | error`. Disable the submit button while submitting and render the result in the page with `aria-live`. Never use `alert()` or `confirm()`.

## Build order

1. **Model the components** in Uniform — `form` first, then fields, then `formButton`, then `formSelectOption`. See [modeling.md](references/modeling.md).
2. **Build a single API route** to receive submissions according to the payload contract. See [submission.md](references/submission.md).
3. **Build the form submission logic** to send submissions according to the payload contract.
5. **Build all components** in the current tech stack and ensure the `<form>` submit event triggers the form submission logic.
6. **Assemble a form in Uniform's visual editor** and submit it to confirm the payload keys match the authored field names.

## Payload contract

The container POSTs this to `/api/forms/submit` which expects the payload contract defined in [submission.md](references/submission.md).
The generic nature of the payload means that it is important to have som

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: uniform-mesh
description: Building Uniform Mesh integrations end to end — scaffold with the CLI, define the mesh-manifest, implement locations, register/install and deploy — plus how to discover and use @uniformdev/design-system components for composing location UI. Covers custom data connectors, Canvas parameter editors, editor tools, personalization algorithms, asset library providers, dashboard/project tools, and edgehancers, on Next.js Page Router (canonical) and App Router (with client-component boundaries). Use when building, scaffolding, or extending a custom Mesh integration, or when choosing and using Uniform design-system components inside a Mesh location.
license: MIT
---

# Uniform Mesh integrations

Build a custom Uniform Mesh integration from a plain use case. A Mesh integration is a
Next.js web app you host, described by a `mesh-manifest.json`, that renders custom UI into
specific **locations** in the Uniform dashboard over iframe messaging. This skill covers
the whole path: turn a use case into the right locations, scaffold, implement with the mesh
SDK and the Uniform design system, and register it. For the exact manifest structure,
always rely on the manifest JSON schema (see `references/manifest.md`) rather than
memorized field lists.

## Build loop

1. **Clarify the use case** — what external system or authoring need, and what the author
   does in the UI (pick a record? edit a value? browse assets?).
2. **Map it to location types** — see the map below and `references/use-case-recipes.md`.
3. **Scaffold or extend** — in a *new* project, `npx @uniformdev/cli@latest new-integration`
   (Page Router Next.js app, API keys, initial registration). In an *existing* project, skip
   the scaffold: add the dependencies and wire the app in place, leaving the existing
   `package.json`, `tsconfig.json`, and framework config intact — merge into them, never
   overwrite them or drop entries you did not add. See `references/build-workflow.md`.
4. **Wire the app** — `MeshApp` provider (Page Router `_app.tsx`, or an App Router client
   provider). Add one page/route per location.
5. **Author the manifest** — per-environment `mesh-manifest.{local,canary,stable}.json`;
   declare each location under `locations`. Validate against the manifest JSON schema
   (`references/manifest.md`).
6. **Implement locations** — `useMeshLocation<'...'>()` for value/metadata; build the UI
   from `@uniformdev/design-system`.
7. **Register + install** — `uniform integration definition register` then
   `uniform integration install <type>`. An integration must be registered to a team and
   installed to a project before it can be tested.
8. **Deploy** — host on HTTPS, point the manifest `baseLocationUrl` at it, re-register.

## Location types → use case (quick map)

Which location serves which use case. The exact manifest keys and fields for each are
defined by the manifest JSON schema — **validate against it** (`references/manifest.md`);
they change across SDK versions, so don't trust field lists memorized here.

| Use case | Location |
|---|---|
| Connect an external system as a data source | data connector |
| Custom Canvas component parameter | parameter type editor |
| Toolbar/tool inside the Canvas editor | editor tool |
| Custom personalization | personalization algorithm |
| External asset provider | asset library / asset parameter |
| Integration-wide config | settings |
| Install-time description | install |
| Tool in the project nav | project tool |
| Tool in the dashboard nav | dashboard tool |

## Two things to always get right

- **The design system is required.** Build all location UI from `@uniformdev/design-system`
  (`Input`, `InputSelect`, `Callout`, `LoadingOverlay`, `ScrollableList`, …) so the
  integration matches the dashboard. Do not hand-roll raw `<input>`/`<select>`/`<button>` or
  add another UI kit. The installed package is the source of truth for what exists and what
  props it takes — `references/design-sys

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: uniform-navigation
description: Model and build header navigation in Uniform — authored, reorderable nav items, dropdown flyouts, mega-menu panels with a category rail and promo area, and mobile drawers. Covers modeling the component chain, the slot-data techniques a parent needs to read its own children, variant-driven layout, and the interaction and accessibility layer. Use when adding a navigation bar, header, navbar, mega menu, flyout, or dropdown menu to a Uniform project, restructuring navigation so editors can author and reorder menu items, adding a mobile navigation drawer, or reviewing a navigation implementation for authoring or accessibility problems.
license: MIT
---

# Uniform navigation and mega menus

Navigation in Uniform is a chain of small components, authored and reordered in the visual
editor. The hard part is that **a slot hands a parent already-rendered, opaque children** —
so a menu shell that needs its children's *labels*, to draw a category rail or a mobile
section heading, cannot get them by reading the slot. Everything here follows from that.

## Workflow

### 1. Discover before you model

Never assume the project is greenfield, and never assume which component library it uses.
Find out which of these you are in — the answer changes every later step. See
[references/discovery.md](references/discovery.md) for the greps.

| What you find | Do |
|---|---|
| Navigation components already exist | **Extend them.** Add the panel/category level; keep existing IDs |
| A header exists but is flat (links only) | Add the flyout + panel levels beneath it |
| Nothing exists | Model the full chain from scratch |

Also determine, before writing any parameter: **is the Design Extensions integration
installed?** If it is not, `dex-*` parameter types produce values your code has no resolver
for. Use plain `select` / `text` / `asset` / `link` types instead.

### 2. Model the chain, not a component

Navigation is a chain of small components, each slot allowing only the next level. Menu
depth is a consequence of **which components a slot allows** — never a depth parameter, and
never numbered parameters (`link1`, `link2`).

```text
header
└── (center slot)  → link | flyout
    └── flyout                            ← trigger + panel shell; variant switches layout
        ├── (panel slot)  → link | group | category
        │   └── category                  ← rail label + its own panel
        │       └── (panel slot) → group | link | image | rich text | layout
        │           └── group             ← labelled column of links
        │               └── (links slot) → link
        └── (aside slot)  → promo content
```

Full slot policy, naming, and the pattern layer: [references/modeling.md](references/modeling.md).

### 3. Wire the parent → child data path *first*

Before any layout work, prove the shell can read its children. This is where navigation
builds fail, and the failure is silent. See
[references/slot-data-access.md](references/slot-data-access.md).

The shape, framework-neutral:

- The **rail** (labels) comes from raw child component instances, read server-side.
- The **panel** (content) comes from rendering the slot normally and filtering to the
  active child by `_id`.

Never rebuild children from raw data — read labels from it, render children through the slot.

### 4. Branch layout on variant, not on a parameter

A dropdown, a full-bleed mega panel, and a master-detail mega panel are the same component
in different layouts. Use a display **variant** for the layout switch and let the presence
of categories pick the sub-shape:

| Variant | Categories present | Layout |
|---|---|---|
| default | — | absolute panel anchored to the trigger |
| mega | none | full-bleed panel, edge to edge |
| mega | one or more | rail + panel, plus optional aside |

Full-bleed panels must be positioned below the header, not below the trigger. Measure the
header's bottom edge on resize and scroll rather than hard-coding 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: uniform-nextjs-app-router
description: Guides integration of Uniform CMS with Next.js App Router using the @uniformdev/next-app-router v2 SDK and React Server Components. Covers project setup, environment variables, required edge middleware and advanced routing, the uniform/[code] composition route, component mapping with resolveComponent, rendering slots and parameters, asset handling, client-side personalization with quirks and scores, contextual editing preview, Next.js 16 cacheComponents, composition data enhancement, and adapter compatibility mode. Use when adding Uniform to a Next.js 16 App Router project, creating Uniform-powered React server components, or configuring live preview, personalization, and caching.
license: MIT
---

# Uniform with Next.js App Router

Integration guide for wiring Uniform CMS to a Next.js application using the App Router. The integration uses React Server Components and the `@uniformdev/next-app-router` package (the **v2** SDK, version `20.58.0` or later).

## Requirements

- **Next.js 16+** and **App Router only** (this v2 SDK does not support the Page Router).
- **Node.js 22+**.
- A Uniform project with compositions.
- On Next.js 15 + Page Router, use the Page Router SDK instead. Migrating Page Router → App Router? Contact Uniform support.

## Quick start

Scaffold a working project instead of integrating from scratch:

```bash
npx @uniformdev/cli@latest new
```

Select **Next.js**, then the **Component Starter Kit** (full-featured) or **Hello World** (minimal). Otherwise follow the manual setup in [references/setup.md](references/setup.md).

## Required packages

`@uniformdev/next-app-router` (version `20.58.0`+), `@uniformdev/canvas` and  `@uniformdev/cli`. For advanced client-side context customization, also add `@uniformdev/next-app-router-client` and `@uniformdev/context`.

## Architecture essentials

- **Middleware is required.** It resolves the route via the Uniform Route API, evaluates personalization/A/B tests at the edge, and rewrites the request to `/uniform/[code]` (where `code` is serialized page state). For Next.js 16, the file MUST be named `middleware.ts` and the config export MUST include `runtime: "experimental-edge"`. Next.js 16.2+ prints a build warning recommending renaming to `proxy.ts` — ignore it and keep `middleware.ts`: `proxy.ts` does not support the edge runtime Uniform requires (renaming fails the build with "Proxy does not support Edge runtime"). The deprecation warning is harmless.
- **The composition route is `app/uniform/[code]/page.tsx`**, not a catch-all. `UniformComposition` fetches and renders the tree, sets up `UniformContext` internally (in `Suspense`), and calls `notFound()` if the route can't resolve.
- **Do NOT place `UniformContext` in `layout.tsx`.** It's handled by `UniformComposition`.
- **Parameters are accessed via the `parameters` object** (`parameters: { title }`), each wrapped in `ComponentParameter<T>` and marked optional.
- **The manifest is fetched at runtime** — no local download needed. Publish it (`uniform context manifest publish`) when you sync manifest definitions; the npm script is optional.
- **Enable `cacheComponents`** (Next.js 16) and import `resolveRouteFromCode` from `@uniformdev/next-app-router/cache` for static-like performance and automatic cache invalidation.

## Key differences from Page Router

| Aspect | App Router (`@uniformdev/next-app-router`) | Page Router |
|--------|-------------------------------------------|-------------|
| Component mapping | `resolveComponent` function | `registerUniformComponent()` registry |
| Routing | `middleware.ts` → `uniform/[code]` route | `withUniformGetServerSideProps` |
| Data fetching | `resolveRouteFromCode` / `createUniformStaticParams` | `getServerSideProps` wrapper |
| Parameter access | `parameters` object, wrapped in `ComponentParameter<T>` | direct prop / registry value |
| Text rendering | `<UniformText component={component} parameter={title} />` | `<UniformTex

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: uniform-nextjs-page-router
description: Guides integration of Uniform CMS with Next.js Page Router. Covers project setup, component registration with registerUniformComponent, fetching compositions with withUniformGetServerSideProps, rendering slots and parameters, contextual editing preview, personalization and A/B testing with Uniform Context, and how the Page Router integration differs from the App Router. Use when adding Uniform to a Next.js Page Router project, creating registered Uniform components, or configuring personalization and A/B testing.
license: MIT
---

# Uniform with Next.js Page Router

Integration guide for wiring Uniform CMS to a Next.js application using the Page Router. The Page Router integration uses `@uniformdev/canvas-next` and `@uniformdev/canvas-react` with SSR via `getServerSideProps`.

## Key differences from App Router

| Aspect | Page Router | App Router |
|--------|------------|-----------|
| Component mapping | `registerUniformComponent()` registry + barrel file | `resolveComponent` function |
| Data fetching | `withUniformGetServerSideProps` in catch-all route | `retrieveRoute` in async server component |
| Imports | `@uniformdev/canvas-next` + `@uniformdev/canvas-react` | `@uniformdev/canvas-next-rsc` |
| Slot rendering | `<UniformSlot name="slotName" />` | `<UniformSlot context={context} data={component} slot={slots.name} />` |
| Text rendering | `<UniformText parameterId="..." placeholder="..." />` | `<UniformText component={component} context={context} parameterId="..." />` |
| Context manifest | Required — download and embed in build | Not needed (handled server-side) |

## Required packages

```
@uniformdev/canvas
@uniformdev/canvas-react
@uniformdev/canvas-next
@uniformdev/context-react
```

## Resources

See `references/` for detailed guidance:
- [Setup](references/setup.md) — Project configuration, composition fetching, component registration pattern
- [Components](references/components.md) — Component registration, typed props, slots, text, rich text, and asset rendering
- [Preview](references/preview.md) — Contextual editing handler, playground page
- [Personalization](references/personalization.md) — Uniform Context setup, manifest download, SSR personalization, A/B testing

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: uniform-sdk
description: Uniform SDK developer reference covering authentication, CLI configuration, routing, and the content API clients that read and write compositions, entries, and content types. Use when setting up Uniform in a frontend project, configuring the CLI, working with the Route API, or reading or writing Uniform content in code with EntryManagementClient, EntryDeliveryClient, CompositionManagementClient, or the deprecated CanvasClient and ContentClient.
license: MIT
---

# Uniform SDK

Framework-agnostic developer reference for integrating Uniform into applications. Covers authentication, the Uniform CLI, routing via Project Map, and the content API clients used to read and write Uniform content from code.


## Key principles

### Always use MCP tools for content operations

CRITICAL: Never manipulate YAML or JSON files in the `uniform-data` folder directly. Always use the Uniform MCP tool for creating, modifying, or deleting components, content types, or any other Uniform entity. After making changes via MCP, run `npm run uniform:pull` to sync the latest state to disk.

### Pin all Uniform packages to the same version

All `@uniformdev/*` npm packages in a project must use the same version. Mismatched versions cause hard-to-debug dependency conflicts and runtime errors. When installing or upgrading, ensure every Uniform package resolves to the identical version number.

### SDK setup checklist

When adding Uniform SDK to a project:
1. Install the appropriate framework-specific packages (all at the same version)
2. Create a component in code for every composition component found in the Uniform project
3. Add all slots from the component definition
4. This ensures preview works correctly

## Resources

See `references/` for detailed guidance:
- [Authentication](references/authentication.md) — API keys, `.env` setup, permissions
- [CLI reference](references/cli-reference.md) — Configuration, push/pull commands, help system
- [Routing](references/routing.md) — Project Map and dynamic route delegation
- [Content API clients](references/clients.md) — Delivery vs management, reading and writing entries, field shapes, deprecated predecessors

Referenced files: 5 — file references are metadata, not package contents.