enonic/nextxp-demo

NextJS ♡ Enonic : Front-end part of the Enonic/Next.js headless CMS demo

This is repo is based on https://github.com/enonic/nextjs-enonic-template and represents the end-result of completing the Next.xp tutorial: https://developer.enonic.com/docs/next.xp

Running demo in the cloud

Follow the TLDR; instructions listed on the front-page of the tutorial referenced above.

Running demo locally

1. Launch local Enonic SDK sandbox (https://developer.enonic.com/start)
2. Launch Enonic XP admin from http://localhost:8080
3. From XP menu - Applications - Install the "Next.js demo" app from Enonic Market (back-end part of demo)
4. Configure and run the Next.js app "nextjs-enonic-demo" (front-end part of demo)

npx degit [email protected]:enonic/nextjs-enonic-demo.git
npm install
npm run dev

Open http://localhost:3000 with your browser to see the result.

Releasing new version

Prepare demo repo

1. Create new features in a branch
2. Test and verify the app
3. Update docs if needed
4. Create pull-request to master on github
5. Tag master using git tag v0.9.0 after pull-request is merged

Update template repo

6. Move all relevant changes to a feature branch in the template repo
7. Test and verify the changes
8. Create pull-request to master on github
9. Tag master branch using git tag v0.9.0 after pull-request is merged

Final step: Release

10. Merge changes to master for both repositories
11. Verify that setting up new next app is working according to tutorial
12. Verify that the TLDR; is working

nextxp-demo's Issues

Serving of attachments and images

Cache and optimize the meta API call

Outline / suggestion:

• Cache the meta API call for content type after the first meta call for a content item.
• After that, only run the data call for that content item.
• Ensure that type is returned with dev-added data queries.
• Compare content type returned with data response with cached content type: if not identical, invalidate that cache item, make the meta call again, and re-cache

CS preview of nextjs page

Content Studio must be able to display a page rendering (SSR or SSG) from nextjs in the preview

Log warning: leaked connection?

From XP server log:

2021-09-15 10:10:52,211 WARN  okhttp3.OkHttpClient - A connection to http://localhost:3000/ was leaked. Did you forget to close a response body? To see where this was allocated, set the OkHttpClient logger level to FINE: Logger.getLogger(OkHttpClient.class.getName()).setLevel(Level.FINE);

Extract XP side to a library

Should probably contain:

• The frontend proxy
• A service for the meta call: content-path => content-type No. This is resolved with the same guillotine API in the new approach.
• Guillotine endpoint? No. Host app should supply its own, this is independent from the frontend proxy funxtionality.
• A service for listing content-paths, used for Next.js SSG (#47 ). No. This is STILL NEEDED, but probably not as part of a frontend proxy lib repo. Independent from that functionality, maybe a lib of its own? Continue on that issue, closing this one.

General next-rendering: Template props are populated from data, and page rendered.

Headless rendering

Make a nextjs app that can request data by guillotine and use the input as props in nextjs components.

• Person
• Movie

Test CS preview

• next.js assets
• next.js /api/ calls
• other local next.js end points?
• activated react components
• dynamic pages with api calls
• JSS
• SSG

Stage 4: Support CS page builder

Second query returns component structure data. Select component-specific TSX.

• Add available component data structure fragments for devs to insert into their queries? Or auto-insert, making queries focus on node data

• How to handle custom component types? Third, fourth queries, depending on their types? Add component structure into the metadata query and use the returned component type structure to compose the data query on the fly? How to handle unknown structure depth in the component tree?

Add / complete unit tests at NextJS side

Finalize docs for NextJS side

Duplicate of #29

After stage 2: write guide

• Intro

• Get started

• Task: add a query with variables: folder

• Task: add component for page rendering

• Preview in CS #37

• Props processing

• Simplify guide:

  • Move the entire Understanding the code section out from chapter 3 (replace with a link or an ultra-compact overview) and into a separate chapter. Appendix? Same as API chapter?
  • Same with the Workflow section in chapter 4.

Stage 2: Type-specific queries and rendering

Select query from first call with CTY. Select rendering from CTY.

• #30
• #31
• #32
• #33

XP side: API for listing content by paths

SSG requires some source for paths to items that should have their HTML be server-side-generated at buildtime, with getStaticPaths. This data must stem from XP at an API point that's contacted at Nextjs buildtime.

Should not be too hard on XP performance. Separate endpoint? Shared / cached etc, updated by task on regular interval or on content update?

Stage 3: Preview next-rendering in CS

Problems:

• #55
• #57
• #58
• #59
• #60 (ok?)
• #61

Finalize:

• #34
• #35
• #36
• #37

Front page controller

Clone:

Default renderer at next, handle any data: displayname, list children

NextJS-rendering of complex CS-built pages

Pages (of different CTY) built in content studio with WYSIWYG components (regions, parts, layouts) should render with NextJS.

General next-rendering: handling missing content and 404

First call: resolve path, get CTY

Second call: support custom query for target CTYs (person, movie)

Extract XP side to library

Second call: fetch data, allow specific query based on returned type from first call

Proof of concept

Make a simple sample app, serving/rendering pages, based on HMDB content and structure (without enonic page templates or page setup).

Front page should have links to child pages, folder should list child items, movie and person should have special templates.

Use gatsby project / headless movie database as starting point.

Things to sort out:

• #17
• #18

Stage 1: MVP dynamic default rendering

Non-type-specific renderer. First call for CTY, second for data.

• #38
• #26
• #27
• #28
• #40

General next-rendering of XP content by path

Instead of rendering XP content using nextJS Pages that know what type of XP content they are and what react templates to use, convert this to a more general approach: the [[pathRouter]].tsx (and draft/[[draftRouter]].tsx).

• #13
• #14
• #15
• #16
• #19
• #20

General next-rendering: Next picks up path (and UUID?) and extracts it

Dual-app setup

Set up a dual-server structure for a NextJS instance and XP to run side by side and communicate

• One git repo (this one), two apps (root-folder-separated)
• Single source of truth, with server urls and a secret token: one common config file for the two apps (or even set of config files for separating different environments?)
  • Can/should this be enforced?
    • Point nextJS to /home/config (at buildtime/runtime)?
    • If the config file(s) doesn't already exist, create it/them at first (XP) run from a template in the repo, and force the dev to change the secret?

Finish the proxy in CS

Issues still standing:

• #55
• #59

General next-rendering: Guillotine is contacted and data fetched

Add / complete unit tests at XP side

Only log the no-query-for-this-type warning in dev mode / draft branch?

There is a console.warn in fetchContent, which says the default query is low-performance and recommends writing a custom query for the current type.

Should that be logged only in next.js dev mode? On draft branch?

General next-rendering: How best to handle layout and SEO?

Exclude media-content-item rendering

Stage 5: Finalizing

• #41
• #42
• #43
• #44
• #36
• #46

Select view (TSX) by CTY

Tighten / complete typescript at NextJS side

Add CS-preview to guide and docs

General next-rendering: React template is chosen by returned content type from a map

Only use the data-dumping _Default.tsx view in dev mode / draft?

Enrich returned content data with type from meta query

Project cleanup: prepare for new structure

404 handling

Client-side rendered next.js pages fail in CS preview

#34

SSR pages so far appear to be rendered correctly in all XP view modes. Client-side rendering however, breaks.

This appears to be connected to the next router (useRouter), which interprets something (something different about the headers?) about the request wrong. asPath becomes [[...contentPath]] etc, instead of persons etc.

Unify API side with HMDB

• Contentdata call should be non-specialized, i.e. use any guillotine API instead of needing the _contentdata endpoint.
• Also generalize the metadata call?

Content-fetching guillotine API

• Set up a guillotine API on the XP side of the dual-app setup
• Must check for the secret in the request
• Must the user supply a guillotine query whenever making a new content type (CTY)?
  • Or can/should there be a CTY-agnostic default query for fetching the content?
  • Can/should a query file (if not exist?) be generated at build time, from the structure of the CTY?
  • Can/should it be overridable?

Make configurable

The settings on both XP side and Next.js side, for communications between the two, are currently hard coded. Make this configurable, from dev/prod-selected .env files, next.js style.

Finish cloning the gatsby starter views

Next routing (frontpage. XP data?) vs XP routing (see navikt project)

Extract frontend-agnostic data-fetching package to NPM

It's possible to extract some of the code from the next.js side to a published NPM package that handles the fetch-data-from-XP part. This package could be used by the next.js starter (or not, to keep the starter more readily changeable), but also supply other frontend frameworks with data: generally a function:

fetchXpData = async (content_path) => content_data

Configurable when it's set up; this package would need the API info (a set of functions?), and a QuerySelector object (a content_type -> guillotine_query map. The NPM package should also internally resolve the last extract-from-guillotine step, since the last key in the returned object (get, getChildren, query etc) depends on the written query).

This will require some refactoring work. Can stay inside the same repo, as long as a subfolder contains all the file necessary to publish a single NPM package from it.

But makes the visualization/frontend/rendering framework much more easily pluggable.