AEM React SPA with Server Side Rendering using Adobe IO

Single page applications are not only in fashion but in demand as well. But, when added with server side rendering it becomes the most complex technology of the current time. It is not easy to get started with server side rendering as it includes some complexities, limitations and difficulties. No worries, with this blog you can understand everything you need to know to implement AEM application with React and SSR.

Generate Project Code

Set up AEM author and publish server as well as docker for dispatcher related stuff. Now lets create new project using below archetype command:

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=42 -D appTitle="SPA Starter Project" -D appId="spa-starter-project" -D artifactId="spa-starter.react" -D groupId="com.adobe.aem.spa.starter" -D frontendModule="react" -D aemVersion="cloud" -D enableSSR=y

Always use latest archetype version to generate new project, enableSSR=y is required in order to generate project SSR enabled. This command will generate starter project code just confirm BUILD SUCCESS message. This code will need few modifications which will be described later in this blog.

Create an Adobe IO project

Created new Adobe IO project on developer console (https://developer.adobe.com/) using App builder template with I/O runtime

After that all you need is NAMESPACE and AUTH keys to be used in further deployment steps. I will recommend to install openwsk for debugging, and checking logs from server side response. To use wsk commands for your project you will need wsk configuration like below.

Download the credentials and copy values to wsk configuration file (c:\users\nitin\.wskprops)

to check wsk working properly type command wsk list and the output will be like this.

Final modifications to the OOTB code

This is most critical step. as it connects AEM deployment along with adobe io ssr action deployment. Below modifications are required in order to use maven to deploy code to local AEM server and adobe io ssr action to adobe io server.

Update OSGi configuration (com.adobe.cq.remote.content.renderer.impl.factory.ConfigurationFactoryImpl~spa-starter-react.cfg.json) with generated NAMESPACE and AUTH values this change can be done to local OSGi console later as well but this makes easy to deploy along with code.

Update POM file with same credentials for the below two values

• aio.runtime.namespace
• aio.runtime.auth

Rename ssr actions common folder to zcommon

This step looks weird but this is a temporary fix by Adobe in order to generate SSR action without any error. Also make sure to rename all occurrences of this folder.

• /actions/ssr/index.js
• manifest.yml

All set, now you can hit maven build command and it should deploy adobe io action as well as complete code to your local AEM.

mvn clean install -PautoInstallPackage -PautoInstallPackagePublish

After that you can hit a page and check wsk logs to see server response. Make sure in console you see the ssr OOTB message hydrated react DOM.

wsk activation list

wsk activation get {activation-id}

Docker for local development

Using docker for local development makes it easy to debug and also helps to debug dispatcher configurations. It becomes very critical when we start implementing URL shortening for pages. Install docker for windows. (https://docs.docker.com/desktop/install/windows-install/)

Go to dispatcher tools folder which came with AEM SDK and to start dispatcher in docker run below command (make sure docker is running)

bin\docker_run C:\codes\spa-starter-react\dispatcher\src host.docker.internal:4503 8080

The above command uses path to your project dispatcher code and 4503 is port for your AEM publish server. Now port 8080 or you can 80 to make it more fun, also make changes to your host file in order to test custom domain. (C:\Windows\System32\drivers\etc\hosts) and add an entry something like

127.0.0.1 spa-starter.com

So now you can access publish pages with https://spa-starter.com/content/..html (instead of localhost:8080/content/..html)

Make sure you have connected your AEM author and publish instances to achieve content published from author to publish. All you need to connect your local author to local publish replication.

Common Problems

1. Request larger than allowed: This Happens when size of ssr json response go more than 1 MB and to fix it you can try to use compression or try to decrease level of depth in SPA root template.
2. Page coming blank: This can occur when there is a mismatch in browser location and the path defined in JSON.
3. URL shortening: This is most complex stuff to do with SPA and ssr as it has some really complex stuff to overlay. (next blog)