Guide to setting up a local development for Adobe Experience Manager, AEM. Covers important topics of local installation, Apache Maven, integrated development environments and debugging/troubleshooting. Development with Eclipse IDE, CRXDE Lite, Visual Studio Code, and IntelliJ are discussed.
Setting up a local development environment is the first step when developing for Adobe Experience Manager or AEM. Take the time to set up a quality development environment to increase your productivity and write better code, faster. We can break an AEM local development environment into four areas:
When we refer to a local AEM instance, we are talking about a copy of Adobe Experience Manager that is running on a developer’s personal machine. All AEM development should start by writing and running code against a local AEM instance.
If you are new to AEM, there are two basic run modes can be installed: Author and Publish. The Author runmode is the environment that digital marketers use to create and manage content. When developing most of the time, you are deploying code to an Author instance. This allows you to create pages and add and configure components. AEM Sites is a WYSIWYG authoring CMS and therefore most of the CSS and JavaScript can be tested against an authoring instance.
It is also critical test code against a local Publish instance. The Publish instance is the AEM environment that visitors to your website interact with. While the Publish instance is the same technology stack as the Author instance, there are some major distinctions with configurations and permissions. The code must be tested against a local Publish instance before being promoted to higher-level environments.
~/aem-sdk
/author
/publish
Rename the QuickStart JAR to aem-author-p4502.jar and place it beneath the /author
directory. Add the license.properties file beneath the /author
directory.
Make a copy of the QuickStart JAR, rename it to aem-publish-p4503.jar and place it beneath the /publish
directory. Add a copy of the license.properties file beneath the /publish
directory.
~/aem-sdk
/author
+ aem-author-p4502.jar
+ license.properties
/publish
+ aem-publish-p4503.jar
+ license.properties
Double-click the aem-publish-p4503.jar file to install the Publish instance. This starts the Publish instance, running on port 4503 on the local computer.
Depending on your development machine’s hardware, it may be difficult to have both an Author and Publish instance running at the same time. Rarely do you need to run both simultaneously on a local setup.
An alternative to double clicking the JAR file is to launch AEM from the command line or create a script (.bat
or .sh
) depending on your local operating system flavor. Below is an example of the sample command:
$ java -Xmx2048M -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303 -jar aem-author-p4502.jar -gui -r"author,localdev"
Here, the -X
are JVM options and -D
are additional framework properties, for more information, see Deploying and Maintaining an AEM instance and Further options available from the Quickstart file.
Apache Maven is a tool to manage the build and deploy procedure for Java-based projects. AEM is a Java-based platform and Maven is the standard way to manage code for an AEM project. When we say AEM Maven Project or just your AEM Project, we are referring to a Maven project that includes all the custom code for your site.
All AEM Projects should be built off the latest version of the AEM Project Archetype: https://github.com/adobe/aem-project-archetype. The AEM Project Archetype provides a bootstrap of an AEM project with some sample code and content. The AEM Project Archetype also includes AEM WCM Core Components configured to be used on your project.
When starting a new project, it is a best practice to use the latest version of the archetype. Keep in mind that there are multiple versions of the archetype and not all versions are compatible with earlier versions of AEM.
PATH
.
$ mvn --version
Apache Maven 3.3.9
Maven home: /Library/apache-maven-3.3.9
Java version: 1.8.0_111, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_111.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
In, the past addition of adobe-public
Maven profile was needed to point nexus.adobe.com
to download AEM artifacts. All AEM artifacts are now available via Maven Central and the adobe-public
profile is not needed.
An integrated development environment or IDE is an application that combines a text editor, syntax support, and build-tools. Depending on the type of development you are doing, one IDE might be preferable over another. Regardless of the IDE, it is important to be able to periodically push code to a local AEM instance in order to test it. It is important to occasionally pull configurations from a local AEM instance into your AEM project in order to persist to a source-control management system like Git.
Below are a few of the more popular IDEs that are used with AEM development with corresponding videos that show the integration with a local AEM instance.
The WKND Project has been updated to default to work on AEM as a Cloud Service. It has been updated to be backwards compatible with 6.5/6.4. If using AEM 6.5 or 6.4, append the classic
profile to any Maven commands.
$ mvn clean install -PautoInstallSinglePackage -Pclassic
When, using an IDE please make sure to check classic
in your Maven Profile tab.
IntelliJ Maven Profile
The Eclipse IDE is one of the more popular IDEs for Java™ development, in large part because it is open source and free! Adobe provides a plugin, AEM Developer Tools, for Eclipse to allow easier development with a nice GUI to synchronize code with a local AEM instance. The Eclipse IDE is recommended for developers new to AEM in large part because of the GUI support by AEM Developer Tools.
The IntelliJ IDEA is a powerful IDE for professional Java™ development. IntelliJ IDEA comes in two flavors, a free Community edition and a commercial (paid) Ultimate version. The free Community version of IntellIJ IDEA is sufficient for more AEM development, however the Ultimate expands its capability set.
Visual Studio Code has quickly become a favorite tool for front-end developers with enhanced JavaScript support, Intellisense, and browser debugging support. Visual Studio Code is open source, free, with many powerful extensions. Visual Studio Code can be set up to integrate with AEM with the help of an Adobe tool, repo. There are also several community-supported extensions that can be installed to integrate with AEM.
Visual Studio Code is a great choice for front-end developers who primarily write CSS/LESS, and JavaScript code to create AEM client libraries. This tool may not be the best choice for new AEM developers since node definitions (dialogs, components) need to be edited in raw XML. There are several Java™ extensions available for Visual Studio Code, however if primarily doing Java™ development Eclipse IDE or IntelliJ may be preferred.
CRXDE Lite is a browser-based view of the AEM repository. CRXDE Lite is embedded in AEM and allows a developer to perform standard development tasks like editing files, defining components, dialogs, and templates. CRXDE Lite is not intended to be a full development environment but is effective as a debugging tool. CRXDE Lite is useful when extending or simply understanding product code outside of your code base. CRXDE Lite provides a powerful view of the repository and a way to effectively test and manage permissions.
CRXDE Lite should be used with other IDEs to test and debug code but never as the primary development tool. It has limited syntax support, no auto-complete capabilities, and limited integration with source control management systems.
Help! My code isn’t working! As with all development, there are times (probably many), where your code is not working as expected. AEM is a powerful platform, but with great power… comes great complexity. Below are a few high level-starting points when troubleshooting and tracking down issues (but far from an exhaustive list of things that can go wrong):
A good first step, when encountering an issue is to verify that the code has been deployed and installed successfully to AEM.
AEM is a chatty platform and logs useful information in the error.log. The error.log can be found where AEM has been installed: < aem-installation-folder>/crx-quickstart/logs/error.log
.
A useful technique for tracking down issues is to add log statements in your Java™ Code:
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
...
public class MyClass {
private final Logger log = LoggerFactory.getLogger(getClass());
...
String myVariable = "My Variable";
log.debug("Debug statement of myVariable {}", myVariable);
log.info("Info statement of myVariable {}", myVariable);
}
By default the error.log is configured to log INFO statements. If you want to change the log level, you can do so by going to Log Support: http://localhost:4502/system/console/slinglog. You may also find that the error.log is too chatty. You can use the Log Support to configure log statements for just a specified Java™ package. This is a best practice for projects, in order to easily separate custom code issues from OOTB AEM platform issues.
All bundles (excluding Fragments) should be in an Active state. If you see your code bundle in an Installed state, then there is an issue that needs to be resolved. Most times this is a dependency issue:
In the above screenshot, the WKND Core bundle is an Installed state. This is because the bundle is expecting a different version of com.adobe.cq.wcm.core.components.models
than is available on the AEM instance.
A useful tool that can be used is the Dependency Finder: http://localhost:4502/system/console/depfinder. Add the Java™ package name to inspect what version is available on the AEM instance:
Continuing with the above example, we can see that the version installed on the AEM instance is 12.2 vs 12.6 that the bundle was expecting. From there, you can work backwards and see if the Maven dependencies on AEM match the Maven dependencies in the AEM project. In, the above example Core Components v2.2.0 is installed on the AEM instance but the code bundle was built with a dependency on v2.2.2, hence the reason for the dependency issue.
AEM components must be backed by a Sling Model to encapsulate any business logic and ensure that the HTL rendering script remains clean. If experiencing issues where the Sling Model cannot be found, it may be helpful to check the Sling Models from the console: http://localhost:4502/system/console/status-slingmodels. This tells you if your Sling Model has been registered and which resource type (the component path) it is tied to.
Shows the registration of a Sling Model, BylineImpl
that is tied to a component resource type of wknd/components/content/byline
.
For most CSS and JavaScript issues, using the browser’s development tools is the most effective way to troubleshoot. To narrow down the issue when developing against an AEM author instance, it is helpful to view the page “as Published”.
Open the Page Properties menu and click View as Published. This opens the page without the AEM Editor and with a query parameter set to wcmmode=disabled. This effectively disables the AEM authoring UI and makes troubleshooting/debugging front-end issues much easier.
Another commonly encountered issue when developing front-end code is old or outdated CSS/JS is being loaded. As a first step, ensure that the browser history has been cleared and if necessary start an incognito browsers or fresh session.
With the different methods of categories and embeds to include multiple client libraries it can be cumbersome to troubleshoot. AEM exposes several tools to help with this. One of the most important tools is Rebuild Client Libraries which force AEM to recompile any LESS files and generate the CSS.
If you are constantly having to invalidate the cache using the Rebuild Client Libraries tool, it may be worth it to do a one time rebuild of all client libraries. This may take around 15 minutes, but typically eliminates any caching issues in the future.