AEM Project Archetype: generating a best-practice AEM site from a Maven command

What the archetype actually generates, and for whom

The AEM Project Archetype is a Maven template that creates a minimal, best-practices-based Adobe Experience Manager project as a starting point for your website. The word minimal is doing real work in that sentence, because the generated project is deliberately not an empty shell.

The features list covers the parts of an AEM site that teams otherwise assemble from documentation by hand. There is a dispatcher configuration, and the documentation is blunt about why that matters: a project is complete only with a dispatcher configuration that ensures speed and security. There is a multi-site option, where the archetype generates the content structure for a multi-language and multi-region setup, backed by the MSM and translation documentation. There is the Core Components set, described as standardised components that let authors create nearly any layout, and editable templates, so a template can be assembled without code and the editable regions define what authors are allowed to change.

Beyond authoring, there is a front-end build so front-end developers can mock AEM pages and build client libraries with Webpack, TypeScript and SASS, and a style system that lets authors apply different styles to components without building custom ones. Responsive layout can be defined on templates or on individual pages for the defined breakpoints, and headers and footers are assembled and localized using the localization features of the components.

The optional paths are worth noting as well. There is a commerce enabled variant for projects integrating with commerce solutions like Magento through the Commerce Integration Framework, and a forms enabled variant. There are ready-to-use functional and UI testing modules, and example code to look at, including a HelloWorld component plus sample models, servlets, filters and schedulers.

One feature is worth calling out because it is unusual for a Maven archetype of this vintage. It is AI agent ready, including an AGENTS.md and a CLAUDE.md to help coding agents understand the project structure and the build commands.

The licence is Apache-2.0, the default branch is develop, and the archetype is published to Maven Central under the com.adobe.aem group.

Running the generate command and the four properties that matter

The usage section gives one command with a handful of adjustable properties, and those properties are the entire configuration surface worth understanding before you run it:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.3.1:generate \
 -D archetypeGroupId=com.adobe.aem \
 -D archetypeArtifactId=aem-project-archetype \
 -D archetypeVersion=58\
 -D appTitle="My Site" \
 -D appId="mysite" \
 -D groupId="com.mysite"

The archetype version follows the release numbering, and the recent releases are aem-project-archetype-58 on 2026-09-18, -57 on 2026-07-03 and -56 on 2025-10-09. The last push to the repository was on 2026-09-18, matching the newest tag.

There are two notes under the command, and both are the kind that cost an afternoon if you miss them. The first says to make sure you use at least version 3.3.1 of maven-archetype-plugin, linking to issue number 400. The second says that to run the command with older versions you have to use the old archetypeGroupId, com.adobe.granite.archetype. In other words, both the plugin version and the group id have moved at some point, and using the current plugin with the old group id, or an old plugin with the new group id, will not work.

The four properties do specific things. appTitle defines the website title and the component groups. appId defines the Maven artifactId, and with it the component, config and content folder names as well as the client library names, so it is not just a label, it determines the layout of your content root. groupId defines the Maven groupId and the Java source package. The documentation also says to look up the list of available properties to see if there is more you want to adjust.

aemVersion decides whether you get the cloud dependency set

The single most consequential property is aemVersion, and the documentation explains its consequences rather than just listing the values.

Setting aemVersion=cloud targets AEM as a Cloud Service, where the documentation says you can go live in few days and that scalability and maintenance are eased. Setting aemVersion=6.5.8 targets Adobe Managed Services or on-premise installations.

The difference that catches people is in the dependencies. The Core Components dependency is only added for non-cloud AEM versions, because the Core Components are provided out of the box for AEM as a Cloud Service. The same applies to the Forms Core Components dependency, which is only added for non-cloud versions for the same reason.

That is a sensible design and a common source of confusion. On a cloud project, the components come from the platform, so adding the dependency would be redundant or conflicting. On an on-premise or AMS project, nothing is provided for you, so the archetype has to pull them in. If you switch a project between those targets later, the dependency list has to change with it, and that is not something the archetype does for you after the fact.

The cloud option also connects to the dispatcher point made earlier, since a project is only complete with a dispatcher configuration, and the archetype is described as generating a dispatcher configuration for the project. There is a separate dispatcher directory referenced in the documentation for the Adobe Managed Services variant of the dispatcher setup, which suggests the generated dispatcher configuration differs between the two targets.

The overall pitch of the cloud option is speed. Rather than assembling the whole stack by hand, you generate a project that is already shaped for the platform you intend to run, and the archetype handles the version differences for you at generation time.

Where the detail lives, and how the project is organised

The README is a summary, and it points at three places for the real information.

The archetype documentation at adobe.com/go/aem_archetype gives a product level overview of the archetype and its general features. The GitHub documentation is the README.md inside src/main/archetype, and it is described as providing detailed technical usage detail of the archetype and all of its modules. The third pointer is a tutorial, the WKND Site, which is described as being based off this archetype and as the place to learn how to start a fresh new website.

That last distinction between the overview and the tutorial is the practical shape of learning this. The archetype reference tells you what the modules are, the WKND tutorial walks through building a site on top of one. Neither replaces the other, and the WKND tutorial being built on the archetype means the paths in it match what the generator produces.

The repository layout is small and conventional. There is a pom.xml at the root, a src directory holding the archetype definition, a.github directory for the workflows, a.vscode directory, and the usual community files in CODE_OF_CONDUCT.md and CONTRIBUTING.md. There is also a COPYRIGHT file and a VERSIONS.md, and the latter is the natural place to look for the compatibility picture across AEM versions. The primary language is recorded as Groovy.

Contributions are welcome, and the project points at its own contributing guide. The last line of the features list is a request to contribute improvements rather than a warning that the project is closed, and the repository is under the Apache-2.0 licence and carries a separate COPYRIGHT file.

What this archetype does not settle for you

An archetype removes setup work, and it is worth being clear about the work it leaves behind.

The first is content and governance. The archetype generates the structure, the templates and the component groups, but what you publish, how your content is structured for authoring, and which components you actually adopt is your decision. The style system exists precisely so that authors apply styles without custom components, which means the design decisions land in the style system and in the template, not in code. That work is where the real effort of an AEM site goes, and the archetype does not touch it.

The second is the custom code. The example code in the generated project, the HelloWorld component and the sample models, servlets, filters and schedulers, is there to show the shape of a custom component. It is scaffolding to replace, not a foundation to build on indefinitely.

The third is version drift. AEM as a Cloud Service is described as easing scalability and maintenance, but the archetype itself is versioned separately, and the releases here move on their own schedule. A project generated from version 58 is generated against the assumptions of that release, and there is no mention in the documentation of a migration path for an existing generated project to a newer archetype version. Newer archetype versions bring new defaults, and the usual Maven answer applies, that you can regenerate and merge, but that is your problem rather than the tool's.

The fourth is the property set itself. The available properties table in the documentation is the authoritative list, and the README explicitly says to look it up to see if there is more you want to adjust. Generating first and configuring later means regenerating, so it is worth reading that table before the first run rather than after.

What the archetype genuinely removes is the initial assembly of a working AEM site, and for a team with no AEM experience that is the difference between a running dispatcher and a page of setup instructions.

Editorial conclusion

Adopt the AEM Project Archetype when you are starting an AEM site and want the dispatcher configuration, core components, editable templates, front-end build and test modules in place from the first commit, rather than assembling them by hand. Do not adopt it for a quick prototype, since it produces a full project structure with a substantial dependency set, and read the property list before generating anything. Before you run the generate command, decide between aemVersion=cloud and aemVersion=6.5.8, because the Core Components and Forms dependencies are only added for the non-cloud path, and use maven-archetype-plugin 3.3.1 or later as the note in the documentation requires.

Frequently asked questions

Official sources

1. adobe/aem-project-archetype on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases