WKND NextJS Template App

This app demonstrates how to write a simple app rendering AEM Pages and Content fragments in Next JS.

Adventures are retrieved from AEM as content fragments using AEM Headless GraphQL API.

Page content is retrieved from AEM as page model using Sling JSON Exporter and can be edited in AEM Remote SPA Editor.

Set up local AEM environment
Bootstrap the Next.js App
Local development
Run in production mode
Run on AEM 6.5
Troubleshooting

Set up local AEM environment

Start the AEM SDK Quickstart

Download and install the AEM SDK Quickstart on port 4502, with default admin/admin credentials.

Download latest AEM SDK
Unzip the AEM SDK to ~/aem-sdk
Run the AEM SDK Quickstart Jar

java -jar aem-sdk-quickstart-xxx.jar

# Provide `admin` as the admin user's password

AEM SDK will start and automatically launch on http://localhost:4502. Log in using the following credentials:

Username: admin
Password: admin

Download and install WKND Site package

This tutorial has a dependency on WKND 1.1.0+'s project (for content).

Download the latest version of aem-guides-wknd.all.x.x.x.zip
Log in to AEM SDK’s Package Manager at http://localhost:4502/crx/packmgr with the admin credentials.
Upload the aem-guides-wknd.all.x.x.x.zip downloaded in step 1
Tap the Install button for the entry aem-guides-wknd.all-x.x.x.zip

Set up AEM Project

In the terminal, create an AEM project in which configurations and baseline content are managed. Always use the latest version of the AEM Archetype.

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \
 -D archetypeGroupId=com.adobe.aem \
 -D archetypeArtifactId=aem-project-archetype \
 -D archetypeVersion=37\
 -D aemVersion=cloud \
 -D appTitle="WKND App" \
 -D appId="wknd-app" \
 -D groupId="com.adobe.aem.guides.wkndapp" \
 -D frontendModule="react"

With the base AEM project is generated, a few adjustments ensure SPA Editor compatibility with Remote Next.js SPAs.

Remove ui.frontend project. Make sure that its references in the root pom.xml file as well as under ui.apps/pom.xml (as a dependency) are also deleted.
Set AEM Page as Next.js Remote SPA Template: open ui.content/src/main/content/jcr_root/content/wknd-app/us/en/home/.content.xml and update it as below.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
          jcr:primaryType="cq:Page">
    <jcr:content
        cq:template="/conf/wknd-app/settings/wcm/templates/spa-next-remote-page"
        jcr:primaryType="cq:PageContent"
        jcr:title="WKND App Home Page"
        sling:resourceType="wknd-app/components/remotepagenext">
        <root
            jcr:primaryType="nt:unstructured"
            sling:resourceType="wcm/foundation/components/responsivegrid">
            <responsivegrid
                jcr:primaryType="nt:unstructured"
                sling:resourceType="wcm/foundation/components/responsivegrid">
                <text
                    jcr:primaryType="nt:unstructured"
                    sling:resourceType="wknd-app/components/text"
                    text="&lt;p>Hello World!&lt;/p>"
                    textIsRich="true">
                    <cq:responsive jcr:primaryType="nt:unstructured"/>
                </text>
            </responsivegrid>
        </root>
    </jcr:content>
</jcr:root>

Note regarding Cross-Origin Resource Sharing (CORS) security policies: make sure that all your desired origins are allowed in ui.config/src/main/content/jcr_root/apps/wknd-app/osgiconfig/config.author.

If you want to use Next v12.2.0 or higher, update the spa.project.core.version value in the root pom.xml file to 1.3.14.

<spa.project.core.version>1.3.14</spa.project.core.version>

Finally, deploy the AEM Project to AEM SDK.

Ensure that AEM Author service is running on port 4502
From the command line, navigate to the root of the AEM Maven project
Use Maven to deploy the project to your local AEM SDK Author service

mvn clean install -PautoInstallSinglePackage

Configure the root AEM page

With the AEM Project deployed, there is one last step to prepare SPA Editor to load your Next.js Remote SPA. In AEM, mark the AEM page that corresponds to the SPA’s root, /content/wknd-app/us/en/home, generated by the AEM Project Archetype.

Log in to AEM Author
Navigate to Sites > WKND App > us > en
Select the WKND App Home Page, and tap Properties
Navigate to the SPA tab
Fill out the Remote SPA Configuration: http://localhost:3000
Tap Save & Close

Update Template Policies

Policies are a feature of AEM templates gives developers and power-users granular control over which components are available to be used. The React Core Components are included in the SPA Code but need to be enabled via a policy before they can be used in the application. By default, the project generated from AEM archetype allows Layout and Text components only.

From the AEM Start screen navigate to Tools > Templates > WKND App.
Select and open the Remote Next.js Page template for editing.
Select the Layout Container and click its policy icon to edit the policy.
Under Allowed Components > WKND App - Content > check Image and Title.
Click Done.

Bootstrap the Next.js App

Run the following npx command to bootstrap your Next.js app from the template.

npx create-next-app \
    -e https://github.com/adobe/aem-nextjs-template \
    --use-npm \
    aem-nextjs-app

Make sure that your .env.development file has the correct values of your local environment. Below is an example.

NEXT_PUBLIC_URL=http://localhost:3000

NEXT_PUBLIC_AEM_HOST=http://localhost:4502
NEXT_GRAPHQL_ENDPOINT=/content/graphql/global/endpoint.json

NEXT_PUBLIC_AEM_SITE=wknd-app
NEXT_PUBLIC_AEM_PATH=/content/wknd-app/us/en/home

Local development

To start developing your app, you first need to install all the npm dependencies.

npm install

Then, execute the below command to run the app in development mode.

npm run dev

Run in production mode

Make sure you update .env.production with your own instances. Then execute the build command.

npm run build

Once it is built successfully, you can start the production server.

npm run start

Run on AEM 6.5

The instructions in Getting Started are mainly targeted at AEM Cloud Service. To make this example work with AEM 6.5.12 or newer - use these steps.

To bootstrap the AEM project - use the archetype as follows:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \
 -D archetypeGroupId=com.adobe.aem \
 -D archetypeArtifactId=aem-project-archetype \
 -D archetypeVersion=37\
 -D aemVersion=6.5.12 \
 -D appTitle="WKND App" \
 -D appId="wknd-app" \
 -D groupId="com.adobe.aem.guides.wkndapp" \
 -D frontendModule="react"

Install aem-guides-wknd.all-1.1.0-classic.zip - the -classic.zip contains all dependencies needed to make the WKND site work on 6.5. The rest of the steps are the same.

(source: duynguyen/aem-nextjs-template#3)

Troubleshooting

Supported browsers

At the current stage, this sample app and in-context editing in AEM work on Google Chrome.
Testing for Firefox and Safari is on the way and might need adjustments to be working without errors.

(source: duynguyen/aem-nextjs-template#4)

Supported Node version

It's recommended to use node version 16.x for now - testing a wider range of node versions is on the way and might need adjustments before they can be used.

(source: duynguyen/aem-nextjs-template#5)

CORS errors from In-context Editing on a production build

When testing locally by running npm run dev, you can load the app at http://localhost:3000 in AEM Remote Editor without any problem.

When running npm run start for a production build, you might see CORS error because you are opening your Next.js app (e.g. localhost:3000) inside AEM (e.g. localhost:4502). You can add some Next configs to allow it or use a browser plugin to bypass CORS (development purpose only).

(source: duynguyen/aem-nextjs-template#6)

adriancom1 / aem-nextjs-template