Front-End Development with the AEM Project Archetype front-end

The AEM Project Archetype includes an optional, dedicated front-end build mechanism based on Webpack. The ui.frontend module thus becomes the central location for all of the project’s front-end resources including JavaScript and CSS files. To fully take advantage of this useful and flexible feature, it is important to understand how front-end development fits into an AEM project.

This document focuses on general usage patterns of the front-end build module and what it does for you. For detailed build options and technical instructions, please see the documentation in the GitHub repository of the archetype.

The latest AEM Project Archetype and associated technical documentation can be found on GitHub.

AEM Front-End and Back-End Development front-end-back-end

In greatly-simplified terms, AEM projects can be thought of as consisting of two separate but related parts:

  • Back-end development that drives the logic of AEM and produces Java libraries, OSGi services, etc.
  • Front-end development that drives the presentation and behavior of the resulting web site and produces JavaScript and CSS libraries

Because these two development processes are focused on different parts of the project, back-end and front-end development can happen in parallel.

front end workflow diagram

However, any resulting project needs to use the output of both of these development efforts i.e. both back-end and front-end.

Determining the Markup determining-markup

Whichever front-end development workflow you decide to implement for your project, the back-end developers and front-end developers must first agree on the markup. Typically AEM defines the markup, which is provided by the core components. However this can be customized if necessary.

Possible Front-End Development Workflows possible-workflows

The front-end build module is a useful and very flexible tool, but imposes no particular opinion on how it should be used. The following are two examples of possible usage, but your individual project needs may dictate other use models.

Using Webpack Static Development Server using-webpack

Using Webpack you can style and develop based on static output of AEM webpages within the ui.frontend module.

  1. Preview page in AEM using page preview mode or passing in wcmmode=disabled in the URL
  2. View page source and save as static HTML within the ui.frontend module
  3. Start webpack and begin styling and generating the necessary JavaScript and CSS
  4. Run npm run dev to generate the clientlibs

In this flow, an AEM developer may perform steps one and two and pass the static HTML off to the front-end developer who develops based on the AEM HTML output.

One could also leverage the Component Library to capture samples of the markup output of each component in order to work at the component level rather than the page level.

Using Storybook using-storybook

Using Storybook you can perform more atomic front-end development. Although Storybook is not included in the AEM Project Archetype, you can install it and store your Storybook artifacts within the ui.frontend module. When ready for testing within AEM, they can be deployed as clientlibs by running npm run dev.

Storybook is not included in the AEM Project Archetype. If you choose to use it, you must install it separately.

Clientlibs Overview clientlibs

The frontend module is made available using an AEM clientlib.. When executing the NPM build script, the app is built and the aem-clientlib-generator package takes the resulting build output and transforms it into such a clientlib.

A clientlib will consist of the following files and directories:

  • css/: CSS files which can be requested in the HTML
  • css.txt: Tells AEM the order and names of files in css/ so they can be merged
  • js/: JavaScript files which can be requested in the HTML
  • js.txt Tells AEM the order and names of files in js/ so they can be merged
  • resources/: Source maps, non-entrypoint code chunks (resulting from code splitting), static assets (e.g. icons), etc.
Learn more about how AEM handles clientlibs in the AEM development documentation abd how to include them in the Core Components documentation.