Next.js tutorial (App Router)
Feature in preview
The SDK for Next.js app router (featuring React Server Components) are in preview and not recommended for production use yet.
This tutorial describes setting up a Uniform-powered composable website in Next.js and Typescript. At the end of this tutorial, you'll learn to:
- Develop a Next.js-powered website and connect your Uniform project.
- Render content created in Uniform on your website.
- Set up a preview of your website on Uniform, and continue building your website in a no-code environment.
1. Create a Next.js project#
Choose a place on your local machine and in that location run the following command to create a Next.js project:
Follow the prompts and select the following options:
Prompt | Response |
---|---|
Project name? | getting-started |
Would you like to use Typescript? | Yes |
Would you like to use ESLint with this project? | Yes |
Would you like to use Tailwind CSS with this project? | Yes |
Would you like to use the src/ directory with this project? Y/N | Yes |
Use App Router (recommended)? | Yes |
Would you like to customize the default import alias ? | No |
The command installs dependencies in your project. Navigate to your codebase once done.
2. Add Uniform SDK#
Install the Uniform packages with the following command:
Under
/app
create a folder called[[...slug]]
withpage.tsx
file in it:
Now dynamic pages are served by the Uniform project map and route API.
3. Configure project connection details#
note
If you don't already have a Uniform account, you can request one at https://uniform.dev/try. You may already have a Uniform project in your dashboard. Either edit this or create a new project, Uniform plan permitting.
Start from your team dashboard in Uniform.
Navigate to Security > API keys.
Click Add API key.
Enter the following values:
Name Project Roles Getting started key
[your project's name]
(it may be auto populated with My first project)Developer (select from the dropdown) Click Create API key.
Create API keyCopy the generated API key and project ID using Copy as .env to place the values on your clipboard.
How to access the 'Copy as .env' controlIn the root of your Next.js project, create a
.env
file to hold all environment variables and secrets. Paste the Uniform API Key and Project ID from clipboard:Add the
.env
file to the.gitignore
file, excluding it from version control.
4. Create a component#
Uniform introduces the concepts of components and compositions. Components are building blocks of content on your website. They match your design system and are similar to components in React.js.
Compositions are a structured collection of components representing a portion of your website, in this case, a page. After creating a component, you'll use it in a composition and then render the composition on the front end.

In the Uniform application, you'll create components to match those in your front-end application, except for the layout component. This is a reversible consideration and assumes you don't want users to modify the layout in Uniform.
- From your team dashboard, select a project and go to Content > Components.
- Click either Create a Component (if this is your first component) or Add component.
- Enter the following values:
Field Value Component name Hero
Public ID hero
(this is auto generated based on the value in "component name")Composition Component Unchecked - Save the component by clicking the arrow in the button and selecting Save.
- Add two parameters - Title (
text
type) and Description (text
type with multi-line). Keep thepublic id
of the parameters lowercase as suggested.
In Uniform, component parameters are fields for data. These map directly to component props in React.
5. Create a composition component#
To create a page, go back to the list of components and repeat the steps to create a component that's a composition. Compositions must be configured as "Composition Components," which form the basis of compositions.
The page composition component uses slots to specify a list of components allowed as children on the page. This is similar to how React uses the children
prop.
Click on the Slots tab in the Page composition component.
Click Add slot.
Enter the following values:
Field Value Slot Name Content Public ID content (this is auto generated based on the value in "Slot Name") Required Component Quantity: Minimum Required Component Quantity: Maximum Allowed Components Allow components and patters "Allowed components" allow you use all components in the Page composition component. The Required Component Quantity option specifies the minimum or maximum number of child components allowed in the slot.
Click OK.
Save and close the component.
6. Create a project map node#
Create a new project map node by going to Content > Project Map.
Click the Add node button.
Enter the following values:
Field Value Name A human-friendly name for your node. If in the "Node type" settings you specified that a new composition should be created, this value is used as the name of the new composition. This field is required. Path segment Select Static or Dynamic. This field is pre-populated from the name field but can be any slug-like string. Node type Select Composition, which means the node represents a composition. Composition Select Assign existing and choose the composition you created in the previous step. Allowed query strings If the "Node type" is set to "Composition," there is an option to add query strings to your path. Select Add query string and enter the field, the default value, and any help text you want to provide authors. Query strings can also be edited or deleted, either from the project map page or from within the composition. Configure a query stringLocation You will choose the location for the node within the tree, whether you create a new composition or placeholder.
Give the node a desired URL segment. This will represent a page.
Afterward, you will be taken to Canvas.
In Canvas you'll see the structure panel on the left, the preview panel in the middle, and the property panel on the right. If you aren't working with the default project, the preview won't be available yet.
- Within the structure panel, click the + under the Content slot to add the Hero component you created earlier as the first item on the page.
- In the property panel, enter the following sample content for each parameter.
- Save and publish the composition.
7. Implement front-end components#
Now you'll bring your own React components into Uniform Canvas.
Create a new folder under the project root:
/canvas
(it can be named anything you want).Create a
Page.tsx
file in the newly-created folder. This page will serve as the component rendering the Page composition and it'scontent
slot:Add your Hero component implementation in
/canvas/Hero.tsx
:This component renders two parameters from the Hero component in Canvas -
title
anddescription
and registers itself with Canvas by callingregisterUniformComponent
.Create a new
index.tsx
file in thecanvas
folder (/canvas/index.tsx
) and import both components:Finally, make sure you import the
/canvas/index.tsx
from your/app/layout.tsx
file:
At this point, your Uniform-powered Next.js app should render on localhost:3000
if you run npm run dev
.
8. Configure live preview#
To activate the preview panel in Uniform, you'll create a Next.js API route containing the preview logic. Uniform ships with a module to set this up.
Create a
route.ts
file under/app/api/uniform
with these contents:Add the secret as an environment variable in your .env file with the following:
Restart your development server, and your preview URL will become:
http://localhost:3000/api/uniform?secret=hello-world
Copy this URL, and in Uniform, navigate to your project and go to: Settings > Canvas Settings and update the URL under Preview Configuration with your new preview URL.
Save the preview URL.
Navigate to your Home node in Uniform, and you should have the preview active.
Summary
- Deploy to Vercel
- Decide cache invalidation strategy.
- Configure webhooks for cache invalidation