NextJS Quick Start Guide

This guide teaches you how to integrate a NextJS website with dotCMS and use the Universal Visual Editor to manage content rendered in the Next.js application.

Overview

dotCMS integrates with Next.js to support a wide assortment of features. In this guide, we'll be focusing on:

Creating and authenticating a Next.js front end for use with the dotCMS back end
Configuring your site to integrate with the Universal Visual Editor (UVE)
Editing content in your new dotCMS project through the UVE

Prerequisites

Node.js & npm: Ensure you have Node.js installed.
Basic Knowledge: Familiarity with Next.js fundamentals and REST API concepts.

Step 1: Create Your Next.js Application

Use the official dotCMS Next.js sample site as a template to create your Next.js application locally. Navigate to the directory you want to install the Next.js application in and run the command below, this will create a Next.js application called my-dotcms-app.

npx create-next-app my-dotcms-app --example https://github.com/dotCMS/core/tree/main/examples/nextjs

This creates a Next.js application that uses localhost:3000 to render in your browser.

Step 2: Configure and Run

Generate an API Token

Before creating your Next.js application, access the demo.dotcms.com instance (or your local instance) and generate an API Access Token for the Admin User:

If accessing the dotCMS demo instance:
- https://demo.dotcms.com/dotAdmin
  - User: admin@dotcms.com
  - PW: admin
- Note: The demo instance is reset twice per day
Create an API Access Token:
- Navigate to Settings > Users
- Select the Admin User
- Click the API Access Tokens tab
- Click the Request New Token button.

Configure the Connection to dotCMS

Open the Next.js application in your code editor and rename the .env.local.example file to .env.local. This file will contain the environment variables for the demo.dotcms.com instance.

Open the .env.local file and update the following environment variables:

NEXT_PUBLIC_DOTCMS_AUTH_TOKEN: This is the API Access Token you generated for the Admin user in the demo.dotcms.com instance in Step 2, above.
NEXT_PUBLIC_DOTCMS_HOST: This is the URL for the demo.dotcms.com instance, which may be https://demo.dotcms.com, http://localhost:8443, or whatever else you've configured for your instance.

Run the Application

Run the dotCMS Next.js example locally to see it in our browser. The Next.js application uses @dotcms/client to acquire data from dotCMS and @dotcms/react to render the Next.js pages and components.

Navigate to the root directory of your Next.js application (e.g. my-dotcms-app) and execute the following:

npm install

npm run dev

Your terminal will output the following, and when you navigate to http://localhost:3000 on your browser, you’ll see the dotCMS Next.js example application running.

Step 3: Universal Visual Editor

The DotCMS Universal Visual Editor (UVE) provides a seamless editing experience directly on your Next.js website. This editor offers a powerful way to build pages, with features including, but not limited to:

In-context editing: Edit content directly on your website
Drag-and-drop interface: Easily arrange components on the page
Responsive design tools: Preview and edit for different screen sizes

Enabling the Universal Visual Editor

Now, we need to configure the Universal Visual Editor application within your dotCMS instance. This will allow it to recognize the local Next.js application and render it in the UVE.

In dotCMS, navigate to Settings > Apps and click on “UVE - Universal Visual Editor”
Click the plus button at the right of the site we're integrating (i.e., demo.dotcms.com).
In the Configuration field, add the following JSON object, which contains the URL for your local Next.js application:

{ "config":
  [
    {
      "pattern": ".*",
      "url": "http://localhost:3000",
    }
  ]
}

Click Save.

Now, navigate to Site > Pages > Home to check out the Next.js application integrated with dotCMS!

Editing Content in the Universal Visual Editor

Now, on to editing the Home page. Try out the following exercises:

Inline text editing

Navigate to Site > Pages > Home if you are not already there.
- Click the title ("Explore the World") and note the in-line editing interface.
- Add some text!
- Click out of the banner area and note the auto-save notification that pops up.
Click on the dropdown at the top left of the screen (which currently says "Draft").
- Select Published; the screen will refresh to the currently published version.
  - This will not show the change you just made — it hasn't been published, yet.
- Now select Preview from the same dropdown.
  - Your draft changes will be visible without the editing controls.
Select Draft from the same dropdown to return to Edit Mode.

Drag and Drop Content

Click on the X icon at the top right of the Explore the World banner
- This will remove the banner once you Accept the change.
  - You will now see an empty container on the page.
In the Content Palette, on the right, browse into the Banner content type by clicking its corner arrow.
Drag a new Banner contentlet into the empty box on the page.
The new banner will render and the page will be saved.

Adjust Layout of the Page Click on the Layout tool in the right side panel

Click on the Layout tool in the rightmost panel.
Drag a Row from the toolbar and drop it below the first existing row.
Grab two more Box items and drag them into the new row.
Resize them all to be equal widths.
Click the Content button in the right panel, and see the four empty containers.

Add Content

Let’s fill the new boxes! Click on the Product content type on the Content Palette.
- If you can't find it, use the search field at the top.
Drag some Products into the empty slots.
Click the mode dropdown in the top left, and select Preview to see how it looks without UVE controls.
Click back to Draft to get back to Edit Mode.
Click the blue Publish button on the top right corner of the screen.

Check Your App!

Now refresh the browser window that has the Next.js application running (localhost:3000), and you will see the changes you made from the back end.

Before

After

You are now up and running — your Next.js site is integrated with dotCMS, and editable through the UVE!