In greatly-simplified terms, AEM projects can be thought of as consisting of two separate but related parts:
Because these two development processes are focused on different parts of the project, back-end and front-end development can happen in parallel.
However, any resulting project needs to use the output of both of these development efforts i.e. both back-end and front-end.
clientlib-dependencies and deposits them in the ui.apps module. ClientLibs are deployable to AEM and allow you to store your client-side code in the repository.
When the entire AEM project archetype is run using
mvn clean install -PautoInstallPackage all project artifacts including the ClientLibs are then pushed to the AEM instance.
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.txtTells 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.
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 you can style and develop based on static output of AEM webpages within the ui.frontend module.
wcmmode=disabledin the URL
npm run devto 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 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.
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.
The AEM Project Archetype includes an optional dedicated front-end build mechanism based on Webpack with the following features.
css.txtfiles are needed as everything is run through Webpack.
/clientlib-siteas well as
For more technical information regarding the ui.frontend module, please see the documentation on GitHub.
You must have run the archetype with the option
-DoptionIncludeFrontendModule=y to populate the ui.frontend folder.
The following npm scripts drive the frontend workflow:
npm run dev- full build with JS optimization disabled (tree shaking, etc) and source maps enabled and CSS optimization disabled.
npm run prod- full build with JS optimization enabled (tree shaking, etc), source maps disabled and CSS optimization enabled.
npm run start- Starts a static webpack development server for local development with minimal dependencies on AEM.
The ui.frontend module compiles the code under the
ui.frontend/src folder and outputs the compiled CSS and JS, and any resources beneath a folder named
resources/folder for layout dependent images and fonts are created in a
dependencies.cssare created in a
The front end build option utilizes dev-only and prod-only webpack config files that share a common config file. This way the development and production settings can be modified independently.
The ui.frontend module build process leverages the aem-clientlib-generator plugin to move the compiled CSS, JS and any resources into the ui.apps module. The aem-clientlib-generator configuration is defined in
clientlib.config.js. The following client libraries are generated:
clientlib-dependencies categories are included on pages via the Page Policy configuration as part of the default template. To view the policy, edit the Content Page Template > Page Information > Page Policy.
The final inclusion of client libraries on the sites page is as follows:
The above inclusion can of course be modified by updating the Page Policy and/or modifying the categories and embed properties of respective client libraries.
Included in the ui.frontend module is a webpack-dev-server that provides live reloading for rapid front-end development outside of AEM. The setup leverages the html-webpack-plugin to automatically inject CSS and JS compiled from the ui.frontend module into a static HTML template.
mvn -PautoInstallSinglePackage clean installto install the entire project to an AEM instance running at
npm run startto start the webpack dev server. Once started it should open a browser (
localhost:8080or the next available port).
You can now modify CSS, JS, SCSS, and TS files and see the changes immediately reflected in the webpack dev server.