CodenTree

When to Use UI.Frontend in AEM

Imagine you’re building a custom theme for an AEM site. Here’s how UI. Frontend helps:

Organized Code: Use the styles folder to manage SCSS files for your theme, like _variables.scss for colors and fonts.

Efficient Builds: The dist folder ensures your compiled CSS and JS are ready for deployment.

Dynamic Assets: Store static images in resources and dynamic ones in DAM.

Scalability: As your project grows, you can add more folders and files without clutter.

Benefits

Fast Loading: Compiled SCSS and JS in the dist folder to ensure optimized, minified code for faster page loads.

Organized Assets: Proper folder structure helps search engines crawl your site efficiently.

Reusable Components: Component-specific SCSS and JS make it easier to maintain and update your site.

Folder Structure in UI.Frontend

The folder structure is key to organizing your SCSS, JS, and other assets. Here’s a breakdown of how it works:

1. UI.Frontend

This is the main folder created by default when you set up an AEM project. It’s where all your front-end code lives.

2. Dist Folder

The dist folder is important. When you build your project (using commands like npm run prod), your CSS and JS files are compiled and placed here. From dist, these files move to ui.apps/clientlibs/(your clientlibs name) and then get exported to the AEM server.

Pro Tip: If you delete the dist folder, don’t worry! Just run the build command again, and it will recreate the folder with all your compiled SCSS and JS files.

3. ProjectName Folder

Inside the src folder, you can create a separate folder (like projectName) to keep all your SCSS, JS, and assets organized. Alternatively, you can use the default components and resources folders. In the screenshot, I’ve created a separate folder for better organization.

4. JS Folder

The js folder is where you store all your JavaScript files. If you’re using packages like Bootstrap, you can either:

Install them via npm and reference them in package.json.

Download the files manually and place them in js/global/. Both approaches have their benefits:
npm approach: Easier to manage and update packages.

Manual download: More control over specific versions and no dependency on npm.

5. Resources Folder

Use the resources folder for static assets like images that won’t change often. For dynamic assets (images that might change), use the AEM DAM (Digital Asset Management) folder.
Example:

From resources: background: url("../resources/images/dotted-pattern.svg");
From DAM: background-image: url(/content/dam/your-folder/img/common/Plus.svg);

6. Styles Folder

The styles folder is where your SCSS files live. You can organize it further:

styles/base: For global files like _variables.scss or package files like _bootstrap.min.scss.
styles/components: For component-specific SCSS files.

You can create more folders inside styles as needed. (Points 6, 7, and 8 from the Main SS are addressed here.)

7. main.js + main.scss

These are the entry points for your project:

In main.scss, import all your SCSS files. Start with package files (if using downloaded packages) and then your custom SCSS files.
In main.js, import main.scss at the top, followed by all your JS files.

Examples

Important Configuration Files

clintlib.config.js

This file is a configuration file for AEM Client Libraries (ClientLibs), using aem-clientlib-generator to manage JavaScript, CSS, and other assets for Adobe Experience Manager (AEM). Let’s go through it step by step:

// path: A Node.js module used to handle and manipulate file paths.
// { dependencies } = require("webpack"): Extracts dependencies from Webpack, but this isn't actually used later in the file.
const path = require("path");
const { dependencies } = require("webpack");


// BUILD_DIR: The output directory where Webpack compiles assets (dist as we discssued above it contain our all complied css+js).
// CLIENTLIB_DIR: The directory inside the AEM project where the ClientLibs are stored (/apps/projectname/clientlibs  .
const BUILD_DIR = path.join(__dirname, "dist");
const CLIENTLIB_DIR = path.join(
  __dirname,
  "..",
  "ui.apps",
  "src",
  "main",
  "content",
  "jcr_root",
  "apps",
  "projectName",
  "clientlibs"
);


// 1. allowProxy: true: Allows accessing the client libraries via /etc.clientlibs/ instead of /apps/eti/clientlibs/.
// 2. serializationFormat: "xml": Defines the format for ClientLibs in AEM (used in .content.xml files).
// 3. cssProcessor: ["default:none", "min:none"]: Disables CSS minification.
// 4. jsProcessor: ["default:none", "min:none"]: Disables JavaScript minification.

const libsBaseConfig = {
  allowProxy: true,
  serializationFormat: "xml",
  cssProcessor: ["default:none", "min:none"],
  jsProcessor: ["default:none", "min:none"],
};

// context: BUILD_DIR: Sets the build directory as the working context.
// clientLibRoot: CLIENTLIB_DIR: Specifies the target directory inside AEM where the client libraries
module.exports = {
  context: BUILD_DIR,
  clientLibRoot: CLIENTLIB_DIR,

  // libs: An array containing multiple ClientLibs definitions.
  libs: [

//  This defines a ClientLib named clientlib-dependencies:
// categories: ["eti.dependencies"]: Used to include this ClientLib in AEM components.
// cwd: "clientlib-dependencies": Looks for assets inside the clientlib-dependencies folder.
// files: ["**/*.js"], ["**/*.css"]: Copies all JavaScript and CSS files.
    {
      ...libsBaseConfig,
      name: "clientlib-dependencies",
      categories: ["projectName.dependencies"],
      assets: {
        // Copy entrypoint scripts and stylesheets into the respective ClientLib
        // directories
        js: {
          cwd: "clientlib-dependencies",
          files: ["**/*.js"],
          flatten: false,
        },
        css: {
          cwd: "clientlib-dependencies",
          files: ["**/*.css"],
          flatten: false,
        },
      },
    },

      // Defines a ClientLib named clientlib-site:
      // categories: ["eti.site"]: Used to load this ClientLib in AEM components.
      // dependencies: ["eti.dependencies"]: Ensures that clientlib-dependencies is loaded first.
      // Also includes non-JS/CSS files in resources, ignoring JS and CSS
    {
      ...libsBaseConfig,
      name: "clientlib-site",
      categories: ["projectName.site"],
      dependencies: ["projectName.dependencies"],
      assets: {
        // Copy entrypoint scripts and stylesheets into the respective ClientLib
        // directories
        js: {
          cwd: "clientlib-site",
          files: ["**/*.js"],
          flatten: false,
        },
        css: {
          cwd: "clientlib-site",
          files: ["**/*.css"],
          flatten: false,
        },

        // Copy all other files into the `resources` ClientLib directory
        resources: {
          cwd: "clientlib-site",
          files: ["**/*.*"],
          flatten: false,
          ignore: ["**/*.js", "**/*.css"],
        },
      },
    },


        // Defines ClientLib clientlib-projectName:
        // categories: ["projectName-site"]: Used in AEM components.
        // dependencies: ["projectName.dependencies"]: Ensures dependent scripts load first.
        // Similar to clientlib-site, it includes JS, CSS, and other assets.
    {
      ...libsBaseConfig,
      name: "clientlib-projectName",
      categories: ["projectName-site"],
      dependencies: ["projectName.dependencies"],
      assets: {
        // Copy entrypoint scripts and stylesheets into the respective ClientLib
        // directories
        js: {
          cwd: "clientlib-projectName",
          files: ["**/*.js"],
          flatten: false,
        },
        css: {
          cwd: "clientlib-projectName",
          files: ["**/*.css"],
          flatten: false,
        },

        // Copy all other files into the `resources` ClientLib directory
        resources: {
          cwd: "clientlib-projectName",
          files: ["**/*.*"],
          flatten: false,
          ignore: ["**/*.js", "**/*.css"],
        },
      },
    },
  ],
};

2. webpack.common.js

webpack.common.js is used to store shared configurations like entry points, output, and loaders.

"use strict";

// node.j plugin
const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const TSConfigPathsPlugin = require("tsconfig-paths-webpack-plugin");
const CopyWebpackPlugin = require("copy-webpack-plugin");
const { CleanWebpackPlugin } = require("clean-webpack-plugin");
const ESLintPlugin = require("eslint-webpack-plugin");

const SOURCE_ROOT = __dirname + "/src/main/webpack";

const resolve = {
  extensions: [".js", ".ts"],
  plugins: [
    new TSConfigPathsPlugin({
      configFile: "./tsconfig.json",
    }),
  ],
};

module.exports = {
  resolve: resolve,
  // Defines the main entry file for your Project
  entry: {
    yourproject: SOURCE_ROOT + "/yourproject/main.js",
  },

  // Controls output structure (clientlib-yourproject/ vs clientlib-dependencies/)
  // [name] dynamically gets replaced with the actual chunk name, so for the yourproject entry, Webpack generates:
  // it will create file with this name inside dist like dist/clientlib-yourproject/yourproject.js
  output: {
    filename: (chunkData) => {
      return chunkData.chunk.name === "dependencies"
        ? "clientlib-dependencies/[name].js"
        : "clientlib-yourproject/[name].js";
    },
    path: path.resolve(__dirname, "dist"), // here we are point to dist folder as we discussed above
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        exclude: /node_modules/,
        use: [
          {
            loader: "ts-loader",
          },
          {
            loader: "glob-import-loader",
            options: {
              resolve: resolve,
            },
          },
        ],
      },
      {
        test: /\.scss$/,
        use: [
          MiniCssExtractPlugin.loader,
          {
            loader: "css-loader",
            options: {
              url: false,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              plugins() {
                return [require("autoprefixer")];
              },
            },
          },
          {
            loader: "sass-loader",
          },
          {
            loader: "glob-import-loader",
            options: {
              resolve: resolve,
            },
          },
        ],
      },
    ],
  },
  resolve: {
    alias: {
      swiper: path.resolve(__dirname, "node_modules", "swiper"),
    },
  },
  plugins: [
    /* will clean old files from the dist folder before generating new ones. 
        The CleanWebpackPlugin automatically deletes files from the dist folder_
        because Webpack's output.path defines where the build files go */
    new CleanWebpackPlugin(), 

    // Checks code quality
    new ESLintPlugin({
      extensions: ["js", "ts", "tsx"],
    }),

    //MiniCssExtractPlugin extracts CSS into a separate file inside 
    //dist/clientlib-emoney/ so that AEM can use it as a client library.
    new MiniCssExtractPlugin({
      filename: "clientlib-yourproject/[name].css",
    }),

    /*This plugin copies static files (like images, fonts, etc.) from the
     source folder (emoney/resources) to dist/clientlib-emoney/ so 
     they can be used in the final build.*/
    new CopyWebpackPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, SOURCE_ROOT + "/yourproject/resources"),
          to: "./clientlib-yourproject/",
        },
      ],
    }),
  ],
  stats: {
    assetsSort: "chunks",
    builtAt: true,
    children: false,
    chunkGroups: true,
    chunkOrigins: true,
    colors: false,
    errors: true,
    errorDetails: true,
    env: true,
    modules: false,
    performance: true,
    providedExports: false,
    source: false,
    warnings: true,
  },
};

Conclusion

In conclusion, using UI.Frontend in AEM helps organize and manage front-end code efficiently. It ensures fast loading through optimized, minified CSS and JS files, and maintains a clear folder structure for scalability. Proper configuration files like `clintlib.config.js` and `webpack.common.js` further streamline the build process, making it easier to maintain and update the site.