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.

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:

PromptResponse
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)?Yes
Would you like to customize the default import alias?No

The command installs dependencies in your project. Navigate to your codebase once done.

  1. Install the Uniform packages with the following command:

  2. Under /app create a folder called [[...slug]] with page.tsx file in it:

Now dynamic pages are served by the Uniform project map and route API.

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.

  1. Navigate to Security > API keys.

  2. Click Add API key.

  3. Enter the following values:

    NameProjectRoles
    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
    Create API key
  5. Copy the generated API key and project ID using Copy as .env to place the values on your clipboard.

    create-api-key
    How to access the 'Copy as .env' control
  6. In 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.

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-compositions
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:
    FieldValue
    Component nameHero
    Public IDhero (this is auto generated based on the value in "component name")
    Composition ComponentUnchecked
  4. Save the component by clicking the arrow in the button and selecting Save.
  5. Add two parameters - Title (text type) and Description (text type with multi-line). Keep the public id of the parameters lowercase as suggested.

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

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.

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

  2. Click Add slot.

  3. Enter the following values:

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

  4. Click OK.

  5. Save and close the component.

Create a new project map node by going to Content > Project Map.

  1. Click the Add node button.

  2. Enter the following values:

    FieldValue
    NameA 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 segmentSelect Static or Dynamic. This field is pre-populated from the name field but can be any slug-like string.
    Node typeSelect Composition, which means the node represents a composition.
    CompositionSelect Assign existing and choose the composition you created in the previous step.
    Allowed query stringsIf 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.
    dynamic-input-query-string
    Configure a query string
    LocationYou 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.

  1. 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.
  2. In the property panel, enter the following sample content for each parameter.
  3. Save and publish the composition.

Now you'll bring your own React components into Uniform Canvas.

  1. Create a new folder under the project root: /canvas (it can be named anything you want).

  2. Create a Page.tsx file in the newly-created folder. This page will serve as the component rendering the Page composition and it's content slot:

  3. Add your Hero component implementation in /canvas/Hero.tsx:

    This component renders two parameters from the Hero component in Canvas - title and description and registers itself with Canvas by calling registerUniformComponent.

  4. Create a new index.tsx file in the canvas folder (/canvas/index.tsx) and import both components:

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

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.

  1. Create a route.ts file under /app/api/uniform with these contents:

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

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

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

  5. Save the preview URL.

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