Next.XP Demo

Contents

What?

You will deploy a Next.js front-end on Vercel, and back-end with content on Enonic respectively - then connect these for a fully working setup.

Want to learn what is really happening? Head on to the first chapter of the tutorial instead.

1 - Setup Enonic

  1. Sign up for a free Enonic account: on https://www.enonic.com/sign-up

  2. After logging in to your account, create a new solution from Solutions → Create → Headless Movie DB. This will install all required Enonic apps and setup the routes needed.

  3. From your new solution, click Environments - Notice the URL to the API ingress, you will need it later.

2 - Create Git repo

To deploy an app on Vercel (the Next.js hosting provider), Vercel will need access to a Git repo with the app code, where you have write access.

Vercel uses this access to automatically fetch and build the app based on events. The write permission is used to setup the required webhooks etc in Github.

  1. Clone or fork https://github.com/enonic/nextxp-demo/ to your personal Github/Bitbucket/Gitlab account.

    If you are using Github, simply press the Fork button at the top right.

3 - Deploy the Next.js front-end

Vercel are the makers of Next.js, and you’ll be using their service to host the front-end.

  1. Sign up to Vercel: https://vercel.com/

  2. Create a new project i.e. enonic-demo, and follow the steps to connect it to the Git repo you created in step 2.

  3. Add environment variables telling the app where to find the API endpoints, as well as a secret you will need to access preview mode in a later step.

    • ENONIC_APP_NAME: com.enonic.app.hmdb

    • ENONIC_API: <URL to the Enonic API root, e.g. https://<environment>/api>;

    • ENONIC_ADMIN: <enonic admin URL> (optional, only if admin is on a different domain than the API)

    • ENONIC_MEDIA_CDN: <media URL> (optional, only if images and attachments are served from a different domain than the API)

    • ENONIC_API_TOKEN: <yourSecret>

    • ENONIC_MAPPINGS: en:hmdb/hmdb

      The MAPPINGS variable defines <locale>:<projectname>/<site-path> to tell the Front-end which project + site to use.
  4. After deploying, the Vercel app should render the front page:

    front page

    Make a note of the Vercel application URL, you will need it when setting up the preview later.

    Check the Vercel function logs if you are not getting the expected result.

4 - Activate preview

With the front-end running, it is time to enable preview in Content Studio.

The fastest way to try it out goes as follows:

  1. Launch Enonic XP admin from the solution dashboard.

  2. No changes needed in Content Studio because Next.js preview widget is already installed in the solution.

  3. We only need to instruct Next.js preview widget where to find the frontend server:

    TODO: Screenshot needs attention — Next.js Preview App

    Go to Applications tab in Enonic Cloud and select Next.js preview app:

    cloud next app edit

    TODO: Screenshot needs attention — Next.js Preview App

    Press Edit…​ button in the app context menu and add the URL and secret of the Vercel app you deployed in step 3:

    cloud next app config

    We are overriding default preview configuration for all sites using the Next.XP app. Use a different keyword than default to define multiple front-ends.
  4. After saving and going back to Content Studio, the preview should update to show your front-end.

    cloud preview

How does it work?

Content Studio will ask every widget if it supports preview, and if so, it will ask the widget to render a preview of the content. When asked, the Next.js preview widget will do following sequence:

  1. send encrypted request to the configured Next.js front-end to fetch XP path to frontend URL mappings

  2. use those mappings to generate a frontend URL for a given content

  3. return it back to Content Studio with the encrypted xp parameter for rendering it directly

  4. when Content Studio loads the URL, the frontend proxy goes through /api/preview if the draft/build or XP-session cookies need synchronization, then redirects to the clean content URL

Your edits will only be visible in Content Studio, until published.

When publishing changes, Next.js preview widget should automatically trigger revalidation of all pages in the front-end, and the changes will go live.

Congratulations, you now have a Next.js site powered by Enonic! 🚀


Contents

Contents