Docs Developer Site
Developer Docs Next.xp Stable Nextjs Setup

Setting up Next.js

Contents

In this chapter we will create a front-end application that renders content from the Enonic CMS (the app created in the previous chapters).

Next.js at a glance

Next.js runs on top of Node.js, and provides a shrink-wrapped approach to building sites using the React framework. Next.js supports both client-side rendering and Server side rendering, as well as pre-generation of static HTML files.

Task: Create the Next.js project

Create an empty folder, go inside and run the following command:

npx degit git@github.com:enonic/nextxp-template.git

The "nextxp-template" is based on Next.js' own introduction app, so if you’re familiar with that, you’ll recognize the structure of the files.

The template includes some boilerplate we will customize, and an npm dependency aka ´The Enonic Adapter` that facilitates and simplifies integration with Enonic.

Code overview

The following file structure should now exist within your new project folder:

Next project files:
.env                                (1)
src/
    middleware.ts                   (2)
    components/                     (3)
    phrases/                        (4)
        en.json
    app/
        [locale]
            [[...contentPath]]/
                page.tsx            (5)
            layout.tsx              (6)
            error.tsx               (7)
            not-found.tsx           (8)
        api/                        (9)
            preview/
                route.tsx
            renderable/
                route.tsx
            revalidate/
                route.tsx
1 Environment variables are placed in this file
2 Middleware file that routes requests based on locale
3 Contains your implementation of CMS components
4 Phrase files for multi-language support
5 The main rendering file, catching all requests satisfying the pattern /[locale]/[[…​contentPath]]
6 Layout file that wraps all pages and adds common structures (eg. <Header>, <LocaleContextProvider>, etc.)
7 Error page handler
8 Not found page handler
9 Folder containing API routes

Task: Configure application

By default, the configuration should work for your setup, but verify it to be sure.

The following configuration values should match your environment:

.env extract:
# Provide a unique value which will be used to secure the preview mode
ENONIC_API_TOKEN=mySecretKey

# Enonic app name, must match the name of your app
ENONIC_APP_NAME=tutorial.nxp

# Enonic XP projects configuration for different locales
ENONIC_MAPPINGS=en:intro/hmdb (1)

# Absolute URL to Content API
ENONIC_API=http://127.0.0.1:8080/site (2)
1 Mapping an XP project (intro) and site (/hmdb) to the Next.js router.
2 Base URL of the Guillotine API, but without project and branch.
These configuration values can be overridden later when deploying your app to a live server.

Task: Boot the server

Let’s fire up the Next.js server and see if things are working as planned…​

Make sure Enonic XP and the Movie DB app are running on localhost:8080 before you continue

Start Next.js in dev mode by running the following commands from within your Next.js project folder:

npm install
npm run dev

If Next boots without errors, point your browser to http://localhost:3000 to see the glorious result.

Application root page, showing debugging details
Page:
{
  "type": "page",
  "path": "/"
}
Common:
{
  "get": {
    "displayName": "hmdb",
    "_id": "3584c396-25cb-497e-b1f4-dc2bf0de4b5a",
    "type": "portal:site",
    "dataAsJson": {
      "description": null
    },
    "xAsJson": {}
  },
  "getSite": {
    "displayName": "hmdb",
    "_path": "/hmdb"
  }
}

Running Next in dev mode normally works fine. Should you however experience "strange issues" - try deleting the .next/ folder and reboot

For more details on booting Next, check out the Next.js CLI docs.

Next URL patterns

The URL structure of your front-end will mirror the structure of the content in the CMS. http://localhost:3000/ will be mounted to the site root, which in our case has the internal path /hmdb.

Using the Movie Se7en as an example:

Result when visiting http://localhost:3000/movies/se7en 
Page:
{
  "type": "page",
  "path": "/"
}
Common:
{
  "get": {
    "displayName": "Se7en",
    "_id": "1cb3dbf4-31d1-4e8a-816a-8cf891de7ad6",
    "type": "tutorial.nxp:movie",
    "dataAsJson": {
      "trailer": "https://youtu.be/znmZoVkCjpI",
      "cast": [
        {
          "actor": "6414dc62-a3a1-4772-961f-06cb85b1bbb7",
          "character": "Somerset"
        },
        {
          "actor": "3a7b833f-3c37-4d55-88ae-cea21c556c68",
          "character": "Mills"
        }
      ],
      "website": null,
      "release": "1995-09-22",
      "subtitle": "Chilling thriller with a plot beyond belief",
      "abstract": "Two detectives, a rookie and a veteran, hunt a serial killer who uses the seven deadly sins as his motives.",
      "photos": [
        "6ca58af1-6810-4fae-b51b-f70e01fc4c17",
        "5cb115db-eb1c-4314-8376-2cb711dea5bd"
      ]
    },
    "xAsJson": {
      "tutorial-nxp": {
        "SoMe": {
          "twitter": null,
          "imdb": "https://www.imdb.com/title/tt0114369/",
          "instagram": null
        }
      }
    }
  },
  "getSite": {
    "displayName": "hmdb",
    "_path": "/hmdb"
  }
}
Se7en as seen in Content Studio - internal path is /hmdb/movies/se7en

se7en edit

Task: Visit some more pages

Give the default rendering a spin by trying out some other URLs, for example:

…​etc.

That’s it for the basic Next.js setup.

Next, we’ll have a closer look at how to customize the rendering.

Contents

Contents

AI-powered search

Juke AI