Next.js tutorial

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. Familiarize yourself with Uniform and its elements.
  2. Model your content and add it to Uniform.
  3. Connect a Uniform composition to your local project using the Composition's slug.
  4. Activate preview for no-code editing in your project.

In this tutorial, you'll follow the following steps to build a uniform-powered project.


You'll need knowledge of:

  • HTML
  • CSS
  • JavaScript
  • React

The knowledge of Next.js and Typescript is optional but beneficial. On your machine, you require access to a terminal with Node.js and its package manager, npm, installed. Alternatively, you can use Yarn.

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:

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/NYes
Use App Router (recommended)?No
Would you like to customize the default import alias?No

The command proceeds to install dependencies in your project. Navigate to your project once done. TailwindCSS will style the components in this project.


Be sure you installed the latest create-next-app version to get the Tailwind installation instructions.

In your local project, navigate to the src/pages/index.tsx file. Replace the contents of the file with this:


Creating the project included installing Tailwind and creating the src/styles/global.css file:

Now you can start your local development server by running the following terminal command:

This creates a local server on localhost:3000. Opening it on the browser looks like this:

Your basic application running on localhost:3000

Like in most Next.js projects, you will build your website's components using JSX markup. In this case, you'll create components for different portions of your application matching your design system. Here's the final project, so you understand the design.

The more granular the components, the better control you afford your non-technical team in Uniform.

Start with building an essential layout component containing a header, footer, and hero component.

Create a folder called components in the /src directory, then add the following component files within src/components.

The components are inspired by TailwindUI Kit.

Header.tsx - A responsive navigation bar.

Footer.tsx - A responsive footer component.

Layout.tsx - Import and render the Header and Footer components.

Hero.tsx - A basic Hero component with a title, highlighted text, and subtitle.

The components you create pass data using props. Uniform utilizes the same props to pass data into the components.

If you don't already have a Uniform account, you can request one at You may already have a Uniform project in your dashboard. Either edit this or create a new project, Uniform plan permitting.

You'll start from your team dashboard.

  1. Navigate to Security > API keys.

  2. Click Add API key.

  3. Enter the following values:

    Getting started key[your project's name] (it may be auto populated with My first project)Developer (select from the dropdown)
  4. Click Create API key.

    Create API key
  5. Copy the generated API key and project ID using Copy as .env and store them somewhere safe. You'll add these to your front-end application soon.

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.

Components within a composition

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.

  1. From your team dashboard, select a project and go to Content > Components.
  2. Click either Create a Component (if this is your first component) or Add component.
  3. Enter the following values:
    Component nameHero
    Public IDhero (this is auto generated based on the value in "component name")
    Component iconImage text
    Title ParameterNone
    Composition ComponentUnchecked
  4. Save the component by clicking the arrow in the button and selecting Save.

In Uniform, component parameters are fields for data. These map directly to component props in React.

  1. In the Parameters tab click Add parameter.

  2. Enter the following values:

    Parameter NameTitle A
    Public IDtitleA (this is auto generated based on the value in "Parameter Name")
    Help Text(Optional. This appears next to the parameter in the Composition editor.)
    Required(Optional. True/False)
    Allow multi-line text(Optional. True/False)
    Validation Regex(Optional)
  3. Click OK.


    In Uniform, the data in parameters can be of primitive types like Text or Number. However, they can also be data from external sources introduced through Uniform integrations. You'll learn more about this in subsequent tutorials.

    The fields for adding a parameter
  4. Continue entering parameters until you have completed the following:

    NameTypePublic ID
    Title ATexttitleA
    Title BTexttitleB
    Highlighted TextTexthighlightedText
  5. Check that each parameter's public ID matches the corresponding prop in the <Hero/> component.

  6. Click Save and close.

The final, configured component.

To create a page, go back to the list of components and repeat the steps to create a component. Compositions must be configured as "Composition Components," which form the basis of compositions. The default project comes with a composition component called "Page.” If you deleted this component or started the project from scratch, create a new component called "Page” and check the "Composition Component" box on the setup page.

Add a text parameter called "Meta Title," make it required, and ignore all other options. This adds meta data to the page.

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.

  1. Click on the Slots tab in the Page composition component

  2. Click Add slot

  3. Enter the following values:

    Slot NameContent
    Public IDcontent (this is auto generated based on the value in "Slot Name")
    Required Component Quantity: Minimum
    Required Component Quantity: Maximum
    Allowed ComponentsAllow 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.

    The configured slot
  4. Click OK.

    Creating a composition component
  5. Save and close the component.

Now that you have configured your components you can use them to create a composition.

  1. Navigate to Content > Compositions.

  2. Click Create a composition (if this is your first composition) or Add composition.

  3. Add the following values:

    Select a composition typePage

    The default project created comes with a Home composition with a route of /. If you deleted the Home composition shipped with the default project, create a new composition called Home with a slug of /. Select Page as the composition type.

    A sample Canvas editor
  4. Click Create.

Once you create a composition you're taken to the Canvas visual editor.

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

The configuration screen for the composition
  1. Within the structure panel, delete any existing components including personalization on the parent "Page" component.

  2. Click the + under the Content slot to add the Hero component you created earlier as the first item on the page.

  3. In the property panel, enter the following sample content for each parameter:

    Title AThe Freedom to Create the
    Highlighted TextWebsites
    Title BYou Want
    SubtextEmpower your non-technical team to build and ship without touching a line of code. Focus on what matters as a developer.
  4. Save and publish the composition.


    Always publish compositions after an update to surface the changes in the frontend.

There are multiple ways to pull data from a Uniform composition into your website. This tutorial fetches the composition by its slug.

  1. In your Next.js project, create a .env file in the root of your project to hold all environment variables and secrets. Add the Uniform API Key and Project ID using the variables:

    Add the .env file to the .gitignore file, excluding it from version control.

  2. Install Uniform Canvas packages with the following command:

  3. In the src/pages/index.tsx file, enable fetching the Uniform composition with a slug matching the current Next.js route and providing it as props to the route component. This should be the first line:


    About this step

    In the block above, you configured Next.js to use the default slug-based composition route resolver and server-side rendering. It's also possible to:

    • Use static rendering (getStaticProps/getStaticPaths exports)

    • Customize the settings or extend the props function, such as fetching only draft compositions:

    • Use alternative route resolution algorithms such as project map (use @uniformdev/canvas-next/project-map instead of @uniformdev/canvas-next/slug in your import)

  4. Next, in the index.tsx file, you'll update the imports with the required modules and render the Composition using the code below:


    About this step

    The UniformComposition component wraps the composition components and receives the composition data as a prop. <UniformSlot/> renders all components added to the slot named content in Uniform. This is the Page composition's content slot's public id.

  5. The last step to visualize the composition is to register your React component with the Uniform SDK so that it knows what to render when it receives a named component.

    In components/Hero.tsx, register it with the Uniform SDK by adding this at the bottom:


    Then import your Hero component file into index.tsx so that the registration becomes visible to the <UniformComposition> component:


    You have now mapped the Hero component to any Uniform component with the public ID of hero.

You should now have a page with a Layout, Hero section, and content coming from Uniform.

Your sample page

With this, you've covered the basics of setting up a Uniform project and connecting it to your Next.js project.

To activate the preview panel in Uniform, you'll create a Next.js API route containing the preview logic. Uniform ships a module to set this up.

  1. In your project, install the Uniform Canvas Next.js package using the command:


    Learn more about the @uniformdev/canvas-next package.

  2. In src/pages/api create a new file called "preview.ts" with the following:


    The code above uses the createPreviewHandler method to set up a preview with contextual editing supported.

  3. Add the secret as an environment variable in your .env file with the following:

  4. Restart your development server, and your preview URL will become: http://localhost:3000/api/preview?secret=uniform.


    Visiting this link in the browser will result in JSON error "{"message":"Couldn't resolve the full path of the preview page"}"

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

  6. Save the preview URL.

  7. Navigate to your Home Composition in Uniform, and you should have the preview active, similar to the image below.

    The Uniform contextual editor showing your application content


Continue building the page by:

  1. Adding more front-end components. Here are sample Features, FeatureCard, CTA, and CTA button components.
  2. Registering the components in the resolveRenderer() function.
  3. Modeling the components on Uniform.
  4. Adding components and content to the composition in Uniform.
  5. Repeat the process above for new pages. Import and reuse functions wherever possible.

Here's the project repository and a deployed version.