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 all of DotCMS's features:

• ✓ Build pages using the Universal Visual Editor (UVE)

• ✓ Edit content directly on your website with real-time previews

• ✓ Preview pages before publishing with full-website previews

• ✓ Model content with DotCMS's content types system

• ✓ Fetch and display DotCMS content using the REST API or GraphQL

• ✓ Write content in multiple languages with localization support

Prerequisites

• DotCMS websites use @dotcms/client, @dotcms/react, and @dotcms/next.

• Node.js & npm/yarn: Ensure you have Node.js installed.

• Basic Knowledge: Familiarity with Next.js fundamentals and REST/API concepts.

Step 1: Access the dotCMS Backend and Generate an API Access Token

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

• Access the dotCMS demo instance:

  • https://demo.dotcms.com/dotAdmin

  • UN: 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 and click the API Access Tokens tab. Click the Request New Token button and create the new token.  This will be used in the Next.js application. 

Step 2: Create Your Next.js Project

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.

Configure Your 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:

• DOTCMS_AUTH_TOKEN: This is the API Access Token you generated for the Admin user in the demo.dotcms.com instance in Step 1 above.

• NEXT_PUBLIC_DOTCMS_HOST: This is the URL for the demo.dotcms.com instance: https://demo.dotcms.com

Run the dotCMS Next.js example locally

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

Key features:

• In-context editing: Edit content directly on your website

• Drag-and-drop interface: Easily arrange components on the page

• Component library: Access all your custom React components

• Responsive design tools: Preview and edit for different screen sizes

• Multi-language support: Edit content in different languages

• Workflow integration: Submit changes for approval within the editor

Enabling the Universal Visual Editor

Now, we need to configure the Universal Visual Editor application within the demo.dotcms.com instance for it to recognize the local Next.js application and render it in the UVE inside the demo.dotcms.com back end.

1. In the demo.dotcms.com instance, navigate to Settings > Apps and click on “UVE - Universal Visual Editor”

2. Click the plus button at the right of demo.dotcms.com, which represents dotCMS’ Demo site the Next.js application is based on.

3. 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",
    }
  ]
}

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

Editing Content in the Universal Visual Editor

Let’s edit the “Home” page.

Inline text edit

• Navigate to Site > Pages > Home if you are not already there.  With the Home page open in the UVE, click into the Banner title “Explore the World” and tab over to the end then add ‘of Code', then click out of the banner area.  The change will auto save and there will be a message flash at the top that it saved.

• Click on the dropdown at the top left of the screen that says ‘Draft’ and select ‘Published’, the screen will refresh to the currently published version, which will not show the change you just made as it is not published yet.

• Now select ‘Preview’ from the same dropdown, the screen will show you the draft version you are working on in Preview mode (without the edit controls) so you can see what your change looks like.

• Now select ‘Draft’ from the same dropdown to get back to the edit mode.

Drag and Drop Content to the page

• Click on the ‘X’ icon at the top right of the Explore the World of Code Banner to remove the banner, click ‘Accept’.  You will now see an empty container on the page.

• Click on the Banner folder in the right hand panel to open up the set of Banners available to place on the page.

• Select the ‘Summer is Here!’ banner (or any other banner) and drag it into the empty box on the page.  The new banner will render and the page will be saved.

Adjust Layout of the page and add content

• Click on the Layout tool in the right side panel

• Drag a ‘Row’ from the Row tool located in the top right of the page and drop it below the first box, then grab an additional three ‘Boxes’ and put them in the new row next to the existing box, resize them all to be equal widths within the new row

• Click the Content tool in the right side panel to go back to the page content, you will see the four empty containers

• Let’s fill them up with Products! Click on the Product content type on the right hand panel (you may need to use the search at the top right to find the Product content type) and drag over a couple of products into the empty slots

• Click the ‘Draft’ button on the top left of the screen, this will bring up a short menu, select ‘Preview’ to check out how the page will look without all the controls of Edit mode

• Click back to Draft to get back to the Editing screen

• Click the Blue ‘Publish’ button on the top right of the screen

• 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

You are now up and running with inline editing and preview of a Next.js application inside dotCMS in less than 10 minutes!

Learn more

[DotCMS Content Types](https://dev.dotcms.com/docs/content-types)

[DotCMS REST API](https://dev.dotcms.com/docs/rest-api)

[Universal Visual Editor](https://dev.dotcms.com/docs/universal-visual-editor)

[Next.js Documentation](https://nextjs.org/docs)