SDK: Next.js Example

dotCMS provides a Next.js example that illustrates how to build dotCMS pages headlessly with the Next.js JavaScript framework and the Universal Visual Editor. What's more, it can be up and running in just five minutes.

What Do You Need?

A dotCMS instance
- To create a local instance, see our Current Releases page
  - A license is required to use the Universal Visual Editor from a local instance
- Or you can use the dotCMS Demo Site
  - No license required
  - The demo site overwrites all public edits every 24 hours
Node.js and npm installed
Terminal or another command shell
A code editor

Instructions

Create the Next.js Application

Open your terminal and create the Next.js app by running the following:

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

This will create a new Next.js app using the dotCMS example.

Configure the Project

Now we need to tell the Next.js app what dotCMS instance is going to use to get the data to build its pages.

Open the folder YOUR_NAME — or whatever you renamed it in the last step — in your code editor.
In the root, find the file .env.local.example and rename it .env.local.
Open the .env.local file and update the environment variable:
- DOTCMS_AUTH_TOKEN: This should be set to an authentication token for dotCMS; use the dotCMS admin panel to create one.
- NEXT_PUBLIC_DOTCMS_HOST: This is the dotCMS instance, as a URL, where your pages and content live; this could be the Demo site URL, a local address, a remote instance, etc.

Run the App

Once all the configuration is in place, it is time to run the web application.

Go back to your terminal and from the folder YOUR_NAME.
Run npm run dev.
Open http://localhost:3000 in your browser.

Local remote site created by the Next.js project.

And that’s it!

As a general note, any page you visit in this environment should exist on the target dotCMS instance. For example, if you browse to localhost:3000/about, the page /about needs to exist in dotCMS.

After the First 5 Minutes

Headless Rendering

To edit the default page rendering, go to /src/app/[[...slug]] and edit page.js. You'll immediately note the changes in the browser. See the Next.js documentation for more information the dynamic routing convention used in that path.

Universal Visual Editing

Follow the instructions under the UVE's Configuration section to set up your App configuration.

Ensure url is set to http://localhost:3000. For simplicity, you can set pattern to .*.

Then browse the dotCMS admin panel to Site -> Pages. Open the Home page (/index). You will now be editing through the proxy of the remote site.

Universal Visual Editor editing a remote site.

Make any edits you wish — for example, click the Pencil icon and edit the banner text, then save the changes.

Finally, reload the remote site at http://localhost:3000, and note the changes reflected.

As a self-study exercise, you may wish to begin by creating new components for Content Types not present in src/components/content-types, and then assigning contentlets of that type through the editor.