Next.js tutorial (App Router)

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:

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:

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

2. Add Uniform SDK#

1. Install the Uniform packages with the following command:

   CopyCopied!Wrap

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

   CopyCopied!Wrap

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

3. Configure project connection details#

Start from your team dashboard in Uniform.

1. Navigate to Security > API keys.

2. Click Add API key.

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

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

   

   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:

   CopyCopied!Wrap

   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.

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:

   Field	Value
   Component name	Hero
   Public ID	hero (this is auto generated based on the value in "component name")
   Composition Component	Unchecked

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.

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.

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

2. Click Add slot.

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

4. Click OK.

5. Save and close the component.

6. Create a project map node#

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

1. Click the Add node button.

2. 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 string
   Location	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.

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.

7. Implement front-end components#

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:

   CopyCopied!Wrap

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

   CopyCopied!Wrap

   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:

   CopyCopied!Wrap

5. Finally, make sure you import the /canvas/index.tsx from your /app/layout.tsx file:

   CopyCopied!Wrap

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.

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

   CopyCopied!Wrap

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

   CopyCopied!Wrap

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.