Docs Developer Site
DeveloperDocsNext.xpStableNextjs Setup

Setting up Next.js

Contents

In this chapter we will create a front-end application that renders pages based on content in the CMS.

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

From an empty folder, 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 a 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 have a look to be sure:

Verify your configuration

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 deplying your app to a live server.

Task: Boot the server

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

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

Start Next.js in dev mode by running the following commands from within your next 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, well have a closer look at how to customize the rendering.

Contents

Contents