# Uniform SDK for Next.js App Router

> Add Uniform to a Next.js 16 App Router app. Set up routes, components, personalization, A/B tests, preview and visual editing.

Source: https://docs.uniform.app/docs/sdk/nextjs-app-router

> **Developer Preview:**
>
> This page documents the developer preview of the SDK, version `20.81.1-alpha.25.sha-f076f9b857`. The APIs can change before the stable release.
>
> - **Changes from the stable SDK:**
>
>   - The middleware makes no API calls.
>   - Every visitor of a route shares one cached page.
>   - Personalization can run at the edge with no flicker.
>
>   Refer to [Upgrade to the developer preview](https://docs.uniform.app/docs/sdk/nextjs-app-router/upgrade-to-developer-preview).
> - **Next.js Pages Router:** use the [Next.js Page Router SDK](https://docs.uniform.app/docs/sdk/nextjs-page-router).
> - **Version 1 of this SDK** (`@uniformdev/canvas-next-rsc`): refer to [Upgrade from v1](https://docs.uniform.app/docs/sdk/nextjs-app-router/upgrade-from-v1).

The Uniform SDK for Next.js App Router (`@uniformdev/next-app-router`) connects a Next.js 16 App Router app to Uniform. The SDK does these tasks:

- It finds the composition for each URL, and applies Uniform redirects.
- It renders the composition with React Server Components.
- It runs personalizations and A/B tests in the browser or at the edge.
- It supports preview and visual editing in Canvas.
- It revalidates the Next.js cache when you publish content.

New to Uniform? Read [Core concepts](https://docs.uniform.app/docs/sdk/nextjs-app-router/concepts) first. It tells you the Uniform terms, and where each term shows up in your code.

To learn how the middleware and the page work together, refer to [How it works](https://docs.uniform.app/docs/sdk/nextjs-app-router/how-it-works).

## Make your AI coding assistant an expert

The [`uniform-nextjs-app-router`](https://github.com/uniformdev/agent-skills/blob/main/skills/uniform-nextjs-app-router/SKILL.md) agent skill gives your AI coding assistant the correct procedures for this SDK. With the skill, the assistant does not invent APIs or use deprecated packages. It knows how to do these tasks:

- Set up the packages, the environment variables and the middleware.
- Add the `uniform/[code]` composition route, and map components in `resolveComponent`.
- Render parameters, slots and assets.
- Configure preview, visual editing, personalization and caching.

Install the skill before you start. The skill works with Claude Code, Codex, GitHub Copilot, Cursor and other agents that read `SKILL.md` files.

| Assistant | Command |
| --- | --- |
| Claude Code | `/plugin marketplace add uniformdev/agent-skills`, then `/plugin install uniformdev@uniformdev` |
| Codex | `codex plugin add uniformdev@openai-curated-remote` |
| GitHub Copilot | `copilot plugin install uniformdev/agent-skills` |
| Other agents | `npx skills add uniformdev/agent-skills` |

The plugins install all Uniform skills. To install only this skill in other agents, run this command:

```bash
npx skills add https://github.com/uniformdev/agent-skills --skill uniform-nextjs-app-router
```

For Cursor, the MCP server and updates, refer to [Uniform agent skills](https://docs.uniform.app/docs/guides/ai/agent-skills#install).

Then tell the assistant your task in your usual words, for example "Add Uniform to this Next.js app so we can manage the homepage." The assistant selects the skill. If it does not, start the skill with `/uniform-nextjs-app-router`.

> **Developer Preview:**
>
> The skill describes the stable SDK. Where the skill and this documentation are different, for example about the middleware, use this documentation.

## Get started

### Prerequisites

- Next.js 16.0.7 or later, with the App Router
- React 19 (React 18.2 is also supported)
- Node.js 20.9 or later
- A Uniform project that has compositions and project map nodes

### Start from a starter project

The fastest procedure is to start from a starter project.

1. Run this command, and select **Next.js**:

   ```bash
   npx @uniformdev/cli@latest new
   ```
2. Select one of the two starters:

   - **Component Starter Kit:** a full starter with components, design tokens and Tailwind CSS. The source is in [uniformdev/component-starter-kit-next-approuter](https://github.com/uniformdev/component-starter-kit-next-approuter).
   - **Hello World:** a minimal app with the essential setup. The source is in [uniformdev/examples/nextjs-app-router](https://github.com/uniformdev/examples/tree/main/examples/nextjs-app-router).

> **Developer Preview:**
>
> The CLI starters can use the stable SDK. To use the developer preview, install the developer preview version of each `@uniformdev` package. Then do the steps in [Upgrade to the developer preview](https://docs.uniform.app/docs/sdk/nextjs-app-router/upgrade-to-developer-preview).

> **Use an AI coding assistant:**
>
> The [`uniform-nextjs-app-router`](https://github.com/uniformdev/agent-skills/tree/main/skills/uniform-nextjs-app-router) agent skill teaches coding assistants such as Claude Code, Codex, Cursor, and Copilot how to add Uniform to a Next.js App Router project: middleware, the composition route, component mapping, preview, personalization, and caching. To install it, see [Uniform agent skills](https://docs.uniform.app/docs/guides/ai/agent-skills).

To add Uniform to an app that you have, do the steps below.

### Install the packages

```bash
v=20.81.1-alpha.25.sha-f076f9b857
npm install @uniformdev/next-app-router@$v
```

`@uniformdev/next-app-router` contains the server SDK, the components, the middleware, the configuration helpers and the preview handlers. It is the only package that you must install.

Install these packages too, if you use the related features:

| Package | Install it when |
| --- | --- |
| `@uniformdev/context` | You write a [custom client context](https://docs.uniform.app/docs/sdk/nextjs-app-router/client-context#custom-client-context), for example to add Context plugins. |
| `@uniformdev/canvas` | You use canvas constants or helpers, for example `CANVAS_PUBLISHED_STATE` or `flattenValues`. |
| `@uniformdev/richtext` | You use rich text types or helpers, for example `ParameterRichTextValue` or `linkParamValueToAnchorProps`. |
| `@vercel/functions` (version 3 or later) | You use the Vercel edge middleware from `@uniformdev/next-app-router/vercel`. |

> **Warning:**
>
> Use the same version for all `@uniformdev` packages. Different versions can install two copies of `@uniformdev/context`, and then the browser Context does not work correctly.

### Set the environment variables

Add these variables to `.env` in the project root:

```bash
UNIFORM_API_KEY=your-api-key
UNIFORM_PROJECT_ID=your-project-id
UNIFORM_PREVIEW_SECRET=your-preview-secret
```

| Variable | Required | Use |
| --- | --- | --- |
| `UNIFORM_PROJECT_ID` | Yes | The project for all API calls. |
| `UNIFORM_API_KEY` | Yes | The API key for all API calls. |
| `UNIFORM_PREVIEW_SECRET` | Yes, for preview | Canvas sends it to the preview handler. Without it, the preview handler answers `401`, also when you turn off draft mode. The webhook handler also checks it when it is set. |
| `UNIFORM_WEBHOOK_SECRET` | No | The Svix signing secret. When it is set, the webhook handler verifies the signature of each webhook. |
| `UNIFORM_API_HOST` or `UNIFORM_CLI_BASE_URL` | No | The host of the Uniform management APIs. The default is `https://uniform.app`. `UNIFORM_CLI_BASE_URL` also sets the CORS origin of the preview handler. |
| `UNIFORM_EDGE_API_HOST` or `UNIFORM_CLI_BASE_EDGE_URL` | No | The host of the Uniform delivery APIs. The default is `https://uniform.global`. |

> **Note:**
>
> You can find the project ID and the API key in your Uniform project under **Security > Service Accounts**. The preview secret is a value that you choose. For more information, refer to the [API access guide](https://docs.uniform.app/docs/guides/api-access).

---

## Add Uniform to your app

The SDK uses these files:

```
your-nextjs-app/
├── app/
│   ├── api/preview/route.ts          # Preview and webhook handler
│   ├── uniform/[code]/page.tsx       # Renders each composition
│   └── playground/[code]/page.tsx    # Renders patterns in Canvas
├── components/resolveComponent.tsx   # Uniform type → React component
├── middleware.ts                     # Makes the code for each request
├── uniform.server.config.ts          # Server configuration
└── next.config.ts                    # Wrapped with withUniformConfig
```

The [Tutorial](https://docs.uniform.app/docs/sdk/nextjs-app-router/tutorial) tells you how to add each file, build your first components, edit them in Canvas, and turn on edge mode.

---

## Next steps

- [How it works](https://docs.uniform.app/docs/sdk/nextjs-app-router/how-it-works)
- [Components and slots in code](https://docs.uniform.app/docs/sdk/nextjs-app-router/components)
- [Personalization and A/B tests](https://docs.uniform.app/docs/sdk/nextjs-app-router/personalization)
- [Edge mode execution](https://docs.uniform.app/docs/sdk/nextjs-app-router/edge-mode)
- [Client-side context](https://docs.uniform.app/docs/sdk/nextjs-app-router/client-context)
- [Middleware configuration](https://docs.uniform.app/docs/sdk/nextjs-app-router/middleware)
- [Preview](https://docs.uniform.app/docs/sdk/nextjs-app-router/preview)
- [Server configuration](https://docs.uniform.app/docs/sdk/nextjs-app-router/configuration)
- [Resolve compositions on a page](https://docs.uniform.app/docs/sdk/nextjs-app-router/resolving-compositions)
- [Caching](https://docs.uniform.app/docs/sdk/nextjs-app-router/caching)
- [Static generation (ISR)](https://docs.uniform.app/docs/sdk/nextjs-app-router/incremental-static-regeneration-isr)
- [Localize your app](https://docs.uniform.app/docs/sdk/nextjs-app-router/localization)
- [Call Uniform APIs on the server](https://docs.uniform.app/docs/sdk/nextjs-app-router/server-clients)
- [Adapter compatibility mode](https://docs.uniform.app/docs/sdk/nextjs-app-router/adapter-compatibility)
- [SDK reference](https://docs.uniform.app/docs/sdk/nextjs-app-router/reference)