Next.js App Router SDK

Developer preview

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

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.

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 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.

The uniform-nextjs-app-router 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.

AssistantCommand
Claude Code/plugin marketplace add uniformdev/agent-skills, then /plugin install uniformdev@uniformdev
Codexcodex plugin add uniformdev@openai-curated-remote
GitHub Copilotcopilot plugin install uniformdev/agent-skills
Other agentsnpx skills add uniformdev/agent-skills

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

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.

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.

  • 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

The fastest procedure is to start from a starter project.

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

    npx @uniformdev/cli@latest new

  2. Select one of the two starters:

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.

Use an AI coding assistant

The 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.

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

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:

PackageInstall it when
@uniformdev/contextYou write a custom client context, for example to add Context plugins.
@uniformdev/canvasYou use canvas constants or helpers, for example CANVAS_PUBLISHED_STATE or flattenValues.
@uniformdev/richtextYou 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.

Add these variables to .env in the project root:

UNIFORM_API_KEY=your-api-key UNIFORM_PROJECT_ID=your-project-id UNIFORM_PREVIEW_SECRET=your-preview-secret
VariableRequiredUse
UNIFORM_PROJECT_IDYesThe project for all API calls.
UNIFORM_API_KEYYesThe API key for all API calls.
UNIFORM_PREVIEW_SECRETYes, for previewCanvas 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_SECRETNoThe Svix signing secret. When it is set, the webhook handler verifies the signature of each webhook.
UNIFORM_API_HOST or UNIFORM_CLI_BASE_URLNoThe 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_URLNoThe 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.

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 tells you how to add each file, build your first components, edit them in Canvas, and turn on edge mode.

Last modified
Next
Core concepts