Tutorial on Creating Adobe Experience Manager (AEM) Maven Project Part 1

An Adobe Experience Manager (AEM) example to demonstrate creating and deploying a Maven Multi-Module project using an aem-project-archetype. This tutorial was created for deployment using Java 11, Apache Maven 3.6.2, Maven AEM Project Archetype 22 and AEM version 6.5.

Requirements

Java 1.8 or Java 11 (AEM 6.5+ only)
Apache Maven (3.3.9+)
Add the adobe-public profile to user Maven settings, e.g., .m2/settings.xml.

More information

Optionally activate the adobe-public profile by default in user Maven settings. The settings.xml for Maven is usually located in the hidden .m2 user directory. To create project specific Maven settings, see Maven - Configuring for Projects.

settings.xml

<profile>

<id>adobe-public</id>

<activation>

<activeByDefault>true</activeByDefault>

</activation>

...

</profile>

Project

In a terminal, in your projects directory, create a directory for the source code. e.g.,

cd myproject

mkdir src

In the source code directory, use mvn to init the project with the desired archetype version. e.g.,

cd src

mvn archetype:generate \

-Padobe-public \

-DarchetypeGroupId=com.adobe.granite.archetypes \

-DarchetypeArtifactId=aem-project-archetype \

-DarchetypeVersion=22

If this is going to be a mutli-lingual site, include property -DisSingleCountryWebsite=n. For default values, see the available properties section of the archetype. Use the -B option to skip the prompts and generate the project in batch mode. e.g.,

mvn archetype:generate -B \

-Padobe-public \

-DarchetypeGroupId=com.adobe.granite.archetypes \

-DarchetypeArtifactId=aem-project-archetype \

-DarchetypeVersion=22 \

-DgroupId=com.adobe \

-Dversion=0.0.1-SNAPSHOT \

-DappsFolderName=myproject \

-DartifactId=aem-dev-myproject \

-Dpackage=com.adobe.aem.dev.myproject \

-DartifactName=myproject \

-DcomponentGroupName=myproject \

-DconfFolderName=myproject \

-DcontentFolderName=myproject \

-DcssId=myproject \

-DpackageGroup=myproject \

-DsiteName=myproject

If you want to include the frontend build process based on Webpack with support for Sass and TypeScript / ES6, use option -DoptionIncludeFrontendModule=general in the archetype:generate. For more information, consult the aem-project-archetype-22/…/ui.frontend/README.md.

Answer the prompts to set up the project. for example,

Property	Value
groupId	com.adobe
version	0.0.1-SNAPSHOT
appsFolderName	myproject
artifactId	aem-dev-myproject
package	com.adobe.aem.dev.myproject
artifactName	myproject
componentGroupName	myproject
confFolderName	myproject
contentFolderName	myproject
cssId	myproject
packageGroup	myproject
siteName	myproject

The artifactId is used for the src maven project folder name. Typically, the groupId and artifactId combine to make the base package. However… NOTE, the base package value cannot contain hyphens. They will be evaluated as a minus sign operators during the Maven build and an error will be thrown. Therefore, we replace the hyphens with periods when combining the groupId and artifactId above. The Adobe WKND Tutorial Chapter, Project Setup contains more information including other examples on how to set up the archtype property values.

Project structure generated by the Maven archetype.

Package Thumbnail

If you would like to add a 64x64 square thumbnail.png image to the package so it is easily identified in AEM Package Manager, then follow this step.

Create a folder named definition in ui.apps/src/main/content/META-INF/vault

Copy your thumbnail.png file into the definition folder.

Also in the definition folder, add a file named .content.xml. with the following:


<?xml version="1.0" encoding="UTF-8"?>

<jcr:root xmlns:vlt="http://www.day.com/jcr/vault/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0">

    <thumbnail.png/>

</jcr:root>

Repeat for ui.content/src/main/content/META-INF/vault

Deploy to AEM

Provided your AEM author instance is running at localhost:4502, navigate to the source project directory created with the artifactId name. e.g.,


cd aem-dev-myproject

mvn -PautoInstallPackage clean install

If your instance is on another port and/or uses non default admin credentials, pass those in as command line parameters. e.g.,


mvn -PautoInstallPackage -Daem.port=4702 -Dvault.username=admin

-Dvault.password='secret' clean install

If you get [ERROR] Unresolveable build extension, try setting activateByDefault to true for the adobe-public profile in the Maven settings here.

If you get repository file read errors, locate the first one and note the file path. e.g.,


[INFO] -------------------------------------------------------------

[ERROR] COMPILATION ERROR :

[INFO] -------------------------------------------------------------

[ERROR] error reading /home/gilfoyle/.m2/repository/commons-beanutils/commons-beanutils/1.8.3/commons-beanutils-1.8.3.jar; zip END header not found

Delete the conflicting files from the repository. In this example, we’re deleting the 1.8.3 folder and its files under commons-beanutils


rm -rf /home/gilfoyle/.m2/repository/commons-beanutils/commons-beanutils/1.8.3

Run the mvn command again, this time with the update option. e.g.,

mvn -U -PautoInstallPackage clean install

The -U option will update the repository.

If everything works as expected, you should get output similar to the following:

Verify the package deployment and installation. For example, open the Package Manager at localhost:4502/crx/packmgr. For this archetype, you should see, aem-dev-myproject.all, aem-dev-myproject.ui.content and aem-dev-myproject.ui.apps packages version 0.0.1-SNAPSHOT installed.

You can do also perform incremental build deployments after making updates. These will run faster since their scope is smaller. e.g.,


cd ui.apps



mvn -PautoInstallPackage -Padobe-public clean install

Core Components

AEM Core Components are included in the project.

To update these components, edit the project pom.xml. For example, in aem-dev-myproject/pom.xml, change the core.wcm.components.version property to 2.8.0. Then run mvn -PautoInstallPackage clean install to deploy the new version of the core components. e.g.,


cd aem-dev-myproject



mvn -PautoInstallPackage clean install

Verify-in Package Manager.

Additional Reading

AEM Archetype Overview
AEM Project Archetype 22 includes a frontend build process based on Webpack, with Sass, CSS preprocessor and TypeScript.
Introduction to Archetypes

AEM Tutorials for Beginners

March 15, 2020
Estimated Post Reading Time ~