adobe / aem-react-spa

Frontend Build: React App

This project provides the front-end code for new AEM projects using the React Decoupled JS archetype option. In this mode, the react app will no longer be bundled into clientlibs, but be built and deploeyed through AEM as a Cloud Service's front-end pipeline.

Usage

To get started, create a new project with the AEM Project Archetype using the decoupled frontend module

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=40 \
 -D appTitle="My Site" \
 -D appId="mysite" \
 -D groupId="com.mysite" \
 -D frontendModule="decoupled"

This will generate a SPA project with the front-end pipeline preconfigured.

In the generated project, with your AEM instance running locally, run mvn install -PautoInstallPackage.

Next create a new repository from this template, clone it, install it and run it

npm install
npm run start

A post install script will ask for the Application Id (appId), which must be the same as before when creating the project from the archetype ("mysite").

This is in particular important as the script adjusts the references to the default content, the resource-type mappings and the package name in the prroject.

Details

Commands

The project and commands are based on Create-React-App.

Commands:

• npm run start Starts the development server. The page can be viewed directly on localhost:3000, or through the AEM editor.
• npm run build Builds a production build to deploy via frontend pipeline TODO how does this deploy step actually work

ENV File

The file .env allows for configuration of the project. Ensure that these variables are set to the correct values, in particular the authorization header.

Most of the environment variables are described in the create react app docs at https://create-react-app.dev/docs/advanced-configuration/.

The following environment variables are specific to this project:

REACT_APP_API_HOST=http://localhost:4502 # The AEM instance that the proxy (see next section) forwards requests to in dev mode
REACT_APP_AEM_AUTHORIZATION_HEADER='Basic YWRtaW46YWRtaW4=' # Authorization header for AEM
REACT_APP_ROOT=/content/aem-react-spa/us/en/home.html # The page that the react app represents
REACT_APP_PAGE_MODEL_PATH=/content/aem-react-spa/us/en.model.json # the page model path on aem for the root page of the react app
REACT_APP_PROXY_ENABLED=true # enable/disable the proxy in LocalDevModelClient (see next section)

Proxy

When accessing the page directly on localhost:3000, the webpack development server acts as a proxy to the AEM content. This is to avoid CORS errors when trying to access the AEM instance directly. The proxy's configuration can be seen in src/LocalDevModelClient.js. Using the proxy requires correct configuration of the variables in .env.

Build output

It is important that the output of the npm run build command is not modified. The config in scripts/webpack.config.js overrides the default Create-React-App config to output the files in a way that the AEM project generated by the archetype expects. Changing the filenames could result in unexpected behaviour and will require additional configuration steps in AEM.

Deployment

The advantage of using the decoupled frontend module with aem-react-spa is that the front-end code can be deployed with AEM's front-end pipeline. This greatly reduces deployment times. To find out more about the front-end pipeline, refer to this article.

The general high-level steps to deploy the project to AEMaaCS are outlined below:

1. In cloud manager, under "Repositories", create a repository for both the AEM archetype code you generated from the archetype and for the front-end code.
2. In cloud manager, under "Pipelines", create a full-stack deployment pipeline and deploy the code you generated from the archetype, using the repository created in the previous step.
3. Create a second pipeline, selecting front-end instead of full-stack this time. Deploy the front-end code repository to this pipeline.
4. Once the deploy is completed, access your AEM author instance. Select the correct front-end module in the front-end panel. Open your page in the editor and verify that it behaves as expected.