Documentação AEM Tutoriais do AEM Tutoriais WKND do AEM Sites

Configuração do projeto project-setup

Last update: Fri Oct 17 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Aplica-se a:
Experience Manager 6.5
Experience Manager as a Cloud Service

Tópicos:
AEM Project Archetype

Criado para:

Iniciante
Desenvolvedor

Este tutorial aborda a criação de um projeto com vários módulos do Maven para gerenciar o código e as configurações de um site do Adobe Experience Manager.

Pré-requisitos prerequisites

Consulte as ferramentas e instruções necessárias para configurar um ambiente de desenvolvimento local. Verifique se você dispõe de uma nova instância do Adobe Experience Manager localmente e se nenhum pacote de amostra/demonstração adicional foi instalado (além dos pacotes de serviços necessários).

Objetivo objective

Aprender a gerar um novo projeto do AEM com um arquétipo do Maven.
Entender os diferentes módulos gerados pelo arquétipo de projeto do AEM e como eles trabalham juntos.
Entender como os componentes principais do AEM são incluídos em um projeto do AEM.

O que você criará what-build

https://video.tv.adobe.com/v/36071?captions=por_br&quality=12&learn=on

Neste capítulo, você gerará um novo projeto do Adobe Experience Manager, usando o Arquétipo de projeto do AEM. O seu projeto do AEM contém o código completo, além de todo o conteúdo e configurações usados em uma implementação do Sites. O projeto gerado neste capítulo servirá de base para uma implementação do site da WKND e será incorporado em capítulos futuros.

O que é um projeto do Maven? - O Apache Maven é uma ferramenta de gerenciamento de softwares para compilar projetos. Todas as implementações do Adobe Experience Manager usam projetos do Maven para compilar, gerenciar e implantar códigos personalizados no AEM.

O que é um arquétipo do Maven? - Um Arquétipo do Maven é um modelo ou padrão para gerar novos projetos. O arquétipo de projeto do AEM ajuda a gerar um novo projeto com um namespace personalizado e incluir uma estrutura de projeto que segue as práticas recomendadas, acelerando bastante o desenvolvimento do projeto.

Criar o projeto create

Há algumas opções para criar um projeto com vários módulos do Maven no AEM. Este tutorial usa o Arquétipo de projeto do do AEM do Maven 35. O Cloud Manager também fornece um assistente de IU para iniciar a criação de um projeto de aplicativo do AEM. O projeto subjacente gerado pela IU do Cloud Manager resulta na mesma estrutura que o uso direto do arquétipo.

NOTE

Este tutorial usa a versão 35 do arquétipo. É considerada uma prática recomendada usar sempre a versão mais recente do arquétipo para gerar um novo projeto.

A próxima série de etapas ocorrerá por meio de um terminal de linha de comando baseado no UNIX®, mas será semelhante ao uso de um terminal do Windows.

Abra um terminal de linha de comando. Verifique se o Maven está instalado:

code language-shell
`$ mvn --version Apache Maven 3.6.2 Maven home: /Library/apache-maven-3.6.2 Java version: 11.0.4, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-11.0.4.jdk/Contents/Home`

Navegue até o diretório no qual deseja gerar o projeto do AEM. Pode ser qualquer diretório no qual você deseja manter o código-fonte do projeto. Por exemplo, um diretório chamado code abaixo do diretório de base do usuário:

code language-shell
`$ cd ~/code`

Cole o seguinte na linha de comando para gerar o projeto no modo de lotes:

code language-shell

code language-shell
`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=39 \ -D appTitle="WKND Sites Project" \ -D appId="wknd" \ -D groupId="com.adobe.aem.guides" \ -D artifactId="aem-guides-wknd" \ -D package="com.adobe.aem.guides.wknd" \ -D version="0.0.1-SNAPSHOT" \ -D aemVersion="cloud"`

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=39 \
    -D appTitle="WKND Sites Project" \
    -D appId="wknd" \
    -D groupId="com.adobe.aem.guides" \
    -D artifactId="aem-guides-wknd" \
    -D package="com.adobe.aem.guides.wknd" \
    -D version="0.0.1-SNAPSHOT" \
    -D aemVersion="cloud"

note note
NOTE
Para direcionar o AEM 6.5.14+, substitua `aemVersion="cloud"` por `aemVersion="6.5.14"`.
Além disso, sempre use o `archetypeVersion` mais recente, consultando Arquétipo de projeto do AEM > Uso

Uma lista completa de propriedades disponíveis para configurar um projeto pode ser encontrada aqui.

As seguintes pasta e estrutura de arquivos são geradas pelo arquétipo do Maven no sistema de arquivos local:

code language-plain

code language-plain
`~/code/ \|--- aem-guides-wknd/ \|--- all/ \|--- core/ \|--- ui.apps/ \|--- ui.apps.structure/ \|--- ui.config/ \|--- ui.content/ \|--- ui.frontend/ \|--- ui.tests / \|--- it.tests/ \|--- dispatcher/ \|--- pom.xml \|--- README.md \|--- .gitignore`

 ~/code/
    |--- aem-guides-wknd/
        |--- all/
        |--- core/
        |--- ui.apps/
        |--- ui.apps.structure/
        |--- ui.config/
        |--- ui.content/
        |--- ui.frontend/
        |--- ui.tests /
        |--- it.tests/
        |--- dispatcher/
        |--- pom.xml
        |--- README.md
        |--- .gitignore

Implantar e compilar o projeto build

Compile e implante o projeto em uma instância local do AEM:

Verifique se há uma instância de criação do AEM em execução localmente na porta 4502.

A partir da linha de comando, navegue até o diretório do projeto aem-guides-wknd.

code language-shell
`$ cd aem-guides-wknd`

Execute o seguinte comando para compilar e implantar o projeto inteiro no AEM:

code language-shell
`$ mvn clean install -PautoInstallSinglePackage`

A compilação leva cerca de um minuto e deve terminar com a seguinte mensagem:

code language-none

code language-none
... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary for WKND Sites Project 0.0.1-SNAPSHOT: [INFO] [INFO] WKND Sites Project ................................. SUCCESS [ 0.113 s] [INFO] WKND Sites Project - Core .......................... SUCCESS [ 3.136 s] [INFO] WKND Sites Project - UI Frontend ................... SUCCESS [ 4.461 s] [INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [ 0.359 s] [INFO] WKND Sites Project - UI apps ....................... SUCCESS [ 1.732 s] [INFO] WKND Sites Project - UI content .................... SUCCESS [ 0.956 s] [INFO] WKND Sites Project - UI config ..................... SUCCESS [ 0.064 s] [INFO] WKND Sites Project - All ........................... SUCCESS [ 8.229 s] [INFO] WKND Sites Project - Integration Tests ............. SUCCESS [ 3.329 s] [INFO] WKND Sites Project - Dispatcher .................... SUCCESS [ 0.027 s] [INFO] WKND Sites Project - UI Tests ...................... SUCCESS [ 0.032 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 23.189 s [INFO] Finished at: 2023-01-10T11:12:23-05:00 [INFO] ------------------------------------------------------------------------

...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for WKND Sites Project 0.0.1-SNAPSHOT:
[INFO]
[INFO] WKND Sites Project ................................. SUCCESS [  0.113 s]
[INFO] WKND Sites Project - Core .......................... SUCCESS [  3.136 s]
[INFO] WKND Sites Project - UI Frontend ................... SUCCESS [  4.461 s]
[INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [  0.359 s]
[INFO] WKND Sites Project - UI apps ....................... SUCCESS [  1.732 s]
[INFO] WKND Sites Project - UI content .................... SUCCESS [  0.956 s]
[INFO] WKND Sites Project - UI config ..................... SUCCESS [  0.064 s]
[INFO] WKND Sites Project - All ........................... SUCCESS [  8.229 s]
[INFO] WKND Sites Project - Integration Tests ............. SUCCESS [  3.329 s]
[INFO] WKND Sites Project - Dispatcher .................... SUCCESS [  0.027 s]
[INFO] WKND Sites Project - UI Tests ...................... SUCCESS [  0.032 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  23.189 s
[INFO] Finished at: 2023-01-10T11:12:23-05:00
[INFO] ------------------------------------------------------------------------

O perfil do Maven autoInstallSinglePackage compila os módulos individuais do projeto e implanta um pacote unificado na instância do AEM. Por padrão, esse pacote é implantado em uma instância do AEM em execução localmente na porta 4502 e com as credenciais de admin:admin.

Navegue até o gerenciador de pacotes na sua instância do AEM local: http://localhost:4502/crx/packmgr/index.jsp. Você verá pacotes para aem-guides-wknd.ui.apps, aem-guides-wknd.ui.config, aem-guides-wknd.ui.content e aem-guides-wknd.all.
Navegue até o console “Sites”: http://localhost:4502/sites.html/content. O site da WKND é um dos sites. Ele inclui uma estrutura do site com uma hierarquia dos EUA e de idiomas principais. Essa hierarquia do site é baseada nos valores de language_country e isSingleCountryWebsite ao gerar o projeto com base no arquétipo.
Abra a página EUA > Inglês, selecionando a página e clicando no botão Editar na barra do menu:
O conteúdo inicial já foi criado, e vários componentes estão disponíveis para ser adicionados a uma página. Experimente esses componentes para ter uma ideia de como funcionam. Você aprenderá as noções básicas dos componentes no próximo capítulo.

Conteúdo de amostra gerado pelo arquétipo

Inspecionar o projeto project-structure

O projeto do AEM gerado é composto por módulos do Maven individuais, cada um com uma função diferente. Este tutorial e a maioria dos desenvolvimentos focam-se nestes módulos:

core: código em Java, principalmente para desenvolvedores de back-end.
ui.frontend: contém código-fonte em CSS, JavaScript, Sass, TypeScript, principalmente para desenvolvedores de front-end.
ui.apps: contém definições de componentes e caixas de diálogo, incorpora o CSS e o JavaScript compilados como bibliotecas de clientes.
ui.content: inclui o conteúdo estrutural e configurações como modelos editáveis, esquemas de metadados (https://experienceleague.adobe.com/content,%20/conf?lang=pt-BR).
all: este é um módulo do Maven vazio que combina os módulos acima em um mesmo pacote que pode ser implantado em um ambiente do AEM.

Diagrama do projeto do Maven

Consulte a documentação do arquétipo de projeto do AEM para mais detalhes sobre todos os módulos do Maven.

Inclusão de componentes principais core-components

Os Componentes principais do AEM são um conjunto de componentes padronizados de gerenciamento de conteúdo da web (WCM, na sigla em inglês) para o AEM. Esses componentes fornecem um conjunto de linha de base de uma funcionalidade e são estilizados, personalizados e estendidos para projetos individuais.

O ambiente do AEM as a Cloud Service inclui a versão mais recente dos Componentes principais do AEM. Portanto, os projetos gerados para o AEM as a Cloud Service não incluem uma integração dos componentes principais do AEM.

Para projetos gerados no AEM 6.5/6.4, o arquétipo incorpora os Componentes principais do AEM ao projeto automaticamente. É uma prática recomendada do AEM 6.5/6.4 incorporar os componentes principais do AEM para garantir que a versão mais recente seja implantada com o seu projeto. Mais informações sobre como os componentes principais são incluídos no projeto podem ser encontradas aqui.

Gerenciamento de controle de origem source-control

É sempre uma boa ideia usar alguma forma de controle do código-fonte para gerenciar o código no seu aplicativo. Este tutorial usa o Git e o GitHub. Há vários arquivos gerados pelo Maven e/ou pelo IDE da sua escolha que devem ser ignorados pelo SCM.

O Maven cria uma pasta de destino sempre que você cria e instala o pacote de código. A pasta de destino e o conteúdo devem ser excluídos do SCM.

No módulo ui.apps, observe que muitos arquivos .content.xml são criados. Esses arquivos XML mapeiam os tipos de nó e as propriedades do conteúdo instalados no JCR. Esses arquivos são cruciais e não podem ser ignorados.

O arquétipo de projeto do AEM gera um arquivo de amostra .gitignore que pode ser usado como ponto de partida e cujos arquivos podem ser ignorados com segurança. O arquivo é gerado em <src>/aem-guides-wknd/.gitignore.

Parabéns! congratulations

Parabéns, você criou o seu primeiro projeto do AEM!

Próximas etapas next-steps

Entenda a tecnologia subjacente a um componente de site do Adobe Experience Manager (AEM) por meio de um exemplo simples de HelloWorld com o tutorial Noções básicas dos componentes.

Comandos avançados do Maven (bônus) advanced-maven-commands

Durante o desenvolvimento, talvez você esteja trabalhando apenas com um dos módulos e queira evitar criar o projeto inteiro para economizar tempo. Você também pode querer implantar diretamente em uma instância de publicação do AEM, ou talvez em uma instância do AEM que não esteja em execução na porta 4502.

Em seguida, vamos rever alguns perfis e comandos do Maven adicionais que você pode usar para obter mais flexibilidade durante o desenvolvimento.

Módulo principal core-module

O módulo core contém todo o código Java™ associado ao projeto. A compilação do módulo core implanta um pacote da OSGi no AEM. Para compilar apenas este módulo:

Navegue até a pasta core (abaixo de aem-guides-wknd):

code language-shell
`$ cd core/`

Execute o seguinte comando:

code language-shell

code language-shell
$ mvn clean install -PautoInstallBundle ... [INFO] --- sling-maven-plugin:2.4.0:install (install-bundle) @ aem-guides-wknd.core --- [INFO] Installing Bundle aem-guides-wknd.core(~/code/aem-guides-wknd/core/target/aem-guides-wknd.core-0.0.1-SNAPSHOT.jar) to http://localhost:4502/system/console via WebConsole [INFO] Bundle installed [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 8.558 s

$ mvn clean install -PautoInstallBundle
...
[INFO] --- sling-maven-plugin:2.4.0:install (install-bundle) @ aem-guides-wknd.core ---
[INFO] Installing Bundle aem-guides-wknd.core(~/code/aem-guides-wknd/core/target/aem-guides-wknd.core-0.0.1-SNAPSHOT.jar) to http://localhost:4502/system/console via WebConsole
[INFO] Bundle installed
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.558 s

Navegue até http://localhost:4502/system/console/bundles. Esse é o console da web da OSGi que contém informações sobre todos os pacotes instalados na instância do AEM.
Alterne a coluna de classificação Id para ver o pacote da WKND instalado e ativo.
Você pode ver a localização “físico” do jar no CRXDE-Lite:

Módulos Ui.apps e Ui.content apps-content-module

O módulo ui.apps do Maven contém todo o código de renderização necessário para o site sob /apps. Isso inclui o CSS/JS que será armazenado em um formato do AEM chamado clientlibs. Também inclui scripts HTL para renderização de HTML dinâmico. Pense no módulo ui.apps como um mapa da estrutura no JCR, mas em um formato que pode ser armazenado em um sistema de arquivos e sujeitado ao controle de origem. O módulo ui.apps contém apenas código.

Para compilar apenas este módulo:

A partir da linha de comando. Navegue até a pasta ui.apps (abaixo de aem-guides-wknd):

code language-shell
`$ cd ../ui.apps`

Execute o seguinte comando:

code language-shell

code language-shell
`$ mvn clean install -PautoInstallPackage ... Package installed in 70ms. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.987 s [INFO] Finished at: 2023-01-10T11:35:28-05:00 [INFO] ------------------------------------------------------------------------`

$ mvn clean install -PautoInstallPackage
...
Package installed in 70ms.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.987 s
[INFO] Finished at: 2023-01-10T11:35:28-05:00
[INFO] ------------------------------------------------------------------------

Navegue até http://localhost:4502/crx/packmgr/index.jsp. Você verá o pacote ui.apps como o primeiro pacote instalado, e ele terá um carimbo de data/hora mais recente que qualquer um dos outros pacotes.

Retorne à linha de comando e execute o seguinte comando (na pasta ui.apps):

code language-shell

code language-shell
$ mvn -PautoInstallPackagePublish clean install ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package-publish) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/sachinmali/Desktop/code/wknd-tutorial/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4503/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.812 s [INFO] Finished at: 2023-01-10T11:37:28-05:00 [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal com.day.jcr.vault:content-package-maven-plugin:1.0.2:install (install-package-publish) on project aem-guides-wknd.ui.apps: Connection refused (Connection refused) -> [Help 1]

$ mvn -PautoInstallPackagePublish clean install
...
[INFO] --- content-package-maven-plugin:1.0.2:install (install-package-publish) @ aem-guides-wknd.ui.apps ---
[INFO] Installing aem-guides-wknd.ui.apps (/Users/sachinmali/Desktop/code/wknd-tutorial/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4503/crx/packmgr/service.jsp
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.812 s
[INFO] Finished at: 2023-01-10T11:37:28-05:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal com.day.jcr.vault:content-package-maven-plugin:1.0.2:install (install-package-publish) on project aem-guides-wknd.ui.apps: Connection refused (Connection refused) -> [Help 1]

O perfil autoInstallPackagePublish deve implantar o pacote em um ambiente de publicação em execução na porta 4503. O erro acima é esperado quando uma instância do AEM em execução em http://localhost:4503 não é encontrada.

Por fim, execute o seguinte comando para implantar o pacote ui.apps na porta 4504:

code language-shell

code language-shell
$ mvn -PautoInstallPackage clean install -Daem.port=4504 ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/dgordon/code/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4504/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] --------------------------------------------------------------------

$ mvn -PautoInstallPackage clean install -Daem.port=4504
...
[INFO] --- content-package-maven-plugin:1.0.2:install (install-package) @ aem-guides-wknd.ui.apps ---
[INFO] Installing aem-guides-wknd.ui.apps (/Users/dgordon/code/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4504/crx/packmgr/service.jsp
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] --------------------------------------------------------------------

Novamente, espera-se que ocorra uma falha de compilação quando nenhuma instância do AEM em execução na porta 4504 está disponível. O parâmetro aem.port está definido no arquivo POM, em aem-guides-wknd/pom.xml.

O módulo ui.content está estruturado da mesma forma que o módulo ui.apps. A única diferença é que o módulo ui.content contém o que é conhecido como conteúdo mutável. O conteúdo mutável refere-se essencialmente a configurações que não são de código, como modelos, políticas ou estruturas de pastas, armazenadas no controle de origem, mas que podem ser modificadas diretamente em uma instância do AEM. Isso será abordado mais detalhadamente no capítulo sobre páginas e modelos.

Os mesmos comandos do Maven usados para criar o módulo ui.apps podem ser usados para criar o módulo ui.content. Você pode repetir as etapas acima na pasta ui.content.

Resolução de problemas

Se houver algum problema ao gerar o projeto com o arquétipo de projeto do AEM, consulte a lista de problemas conhecidos e a lista de problemas em aberto.

Parabéns novamente! congratulations-bonus

Parabéns por ter passado pelo material de bônus.

Próximas etapas next-steps-bonus

Entender a tecnologia subjacente a um componente de site do Adobe Experience Manager (AEM) por meio de um exemplo simples do HelloWorld com o tutorial Noções básicas dos componentes.

recommendation-more-help

b2a561c1-47c0-4182-b8c1-757a197484f9