FAQ

If you're coming from AEM Boilerplate or Block Collection, you may notice some foundational differences with Author Kit. The following FAQ should hopefully answer the most common questions.

Why are sections decorated slightly different than AEM Boilerplate?

Boilerplate's section classes are created based on the blocks inside them. As such, a section could have hero-container, columns-container, or both: hero-container columns-container. Developers are then required to know up front all possible combinations when using these classes. This is also in addition to any styles that may be applied from section metadata. It's far too easy to run into scoping and specificity issues when working with classes setup this way.

Author Kit follows patterns that are more similar to common industry patterns like Bootstrap and Tailwind. You have a section, a container, and then default content or block content. Each continuous group of content (default or blocks) will be placed into a container that you can style.

Why does section content default to full width instead of being in a container?

We believe the best code is no code. We also believe code is more readable when you opt-in rather than opt-out. I would encourage you to look at the hero block of AEM Boilerplate. The very first property is max-width: unset. This is saying, "The very first thing I need you to is undo the styles being forced upon me."

Why is there dedicated section-metadata JS & CSS?

We have found section-metadata to be a powerful pattern to control layouts surrounding blocks. It's also quite common to not need section-metadata when working with higher priority or LCP-bound blocks (hero, etc). As such, placing all section styles in styles.css and putting section logic in the critical path of LCP to be non-ideal. It's a core Edge Delivery principle: only load styles and logic when you need them.

Why is there a "Card" block and not a "Cards" block?

The authoring ergonomics of calling a singleton something plural can fall down when you want to style an individual item. Example: "I want to style one card in my cards block, how do I do this?" Note: there is a tradeoff here. You will end up making more table-based blocks if you have many authored cards. If you prefer to have a "cards" block, you can always make one.

Keeping consistent pluralization patterns for authors helps with discoverability and reduces training. Which also goes hand in hand with keeping a leaner and more maintainable codebase. The way your organize a series of card blocks is the exact same way you handle a series of teaser(s), video(s), and more. Structurally, keeping these the same will require fewer mental hurdles when writing layout code section metadata.

Why do I need to specify a production hostname for my project?

It's not required, but it is recommended. For two reasons:

1. It's quite common for authors to copy production URLs to paste into their documents. These are not converted to relative on aem.TLD URLs. When this happens, pre-production visitor journeys break and cause confusion and frustration. Author Kit will identify links using the hostname and make them relative and respect the visitor journey.
2. Because production URLs can land as fully qualified / non-relative URLs, we would have no path to localize the URL if a locale-agnostic link has been used.

It's unfortunate these are now specified in multiple places: Config Bus, code, etc. but we feel this is creates the best experience for all personas: author, administrator, QA, and developer.

Why are fragments and other "embed" type blocks required to be a link?

Given the purposefully flat structure of Edge Delivery documents, it's quite common to need "just one more" layer of nesting. This could be anything from placing a youtube video next to text inside some columns or placing columns inside a tab component. We've seen a lot of awkward implementations to work around the section > block relationship. Codifying section > block > link as a repeatable and useable pattern alleviates a lot of these poor implementations.

My site is not multilingual, do I need locales?

No. You can remove this.

Why is AEM Opterational Telemetry (RUM) a separate file?

First and foremost, there should be no material performance penatly having this as a separate file. This is purely a separation of concerns choice. The functions that decorate your site and the functions that fulfill your contractual obligations to Adobe should be treated separately.

Why is ak.js so much smaller than aem.js?

A few reasons.

1. Author Kit heavily leans into Edge Delivery best practices. It often subscribes to these principles more than Boilerplate. Here's an example: Adobe will often tell developers not to place any code in the critical path of LCP. If you look at aem.js, you will find many functions not needed to get to LCP: createOptimizedPicture, buildBlock, decorateIcon, readBlockConfig, etc. Author Kit places these non-critical functions into separate files that can be used when needed.
2. As noted above, ak.js also does not include RUM functions itself.
3. Author Kit simply works more efficiently having been created based on lessons learned from many real-world projects.

Why is Author Kit seemingly faster than Boilerplate?

Both projects are incredibly fast, but there are some limited scenarios where Author Kit is faster. This has a lot to do with the micro optimizations sprinkled through out the codebase. A few examples:

1. The overall codebase is smaller. Beyond what was mentioned above, there are fewer eslint-disable statements, smaller functions, less redundant functions, etc. Fewer bytes over the wire means faster responses. This is especially true when it comes to delivering the LCP element.
2. Icons are only loaded for the immediate section being loaded, not all icons for the entire page.
3. There's less DOM manipulation happening during decoration. Fewer class names being added, fewer data attributes, fewer synthetic blocks, etc.
4. Using for instead of forEach is shown to be more efficient (though only in extreme cases).
5. It is obsessively parallelized where possible. If an async function or module can be run or imported concurrently without any performance pentalty, Author Kit will do it.

Am I losing any functionality?

Mostly the opposite. Author Kit prides itself on having more knobs and dials to help your project scale. We believe the features in Author Kit are a matter of when your project needs them, not a matter of if they will need them. The README of this codebase covers many of these features.

What is known to be missing

1. There is no lighthouse=on check - We believe you should be transparent about performance of a page.
2. There is no synthetic hero block built - This has proven to cause confusion with authors and developers alike.
3. There is no delayed.js - Only create this if you truly need it.

What's the catch if I use Author Kit?

1. Author Kit is a community project publicly maintained by Adobe employees. As of this writing, it is not an official boilerplate and thus, it is not officially supported beyond Discord and public GitHub issues.
2. The notable differences above makes Author Kit a poor upgrade from a Boilerplate-based project. Much like comparing traditional AEM to Edge Delivery; there is no free lunch. New features and radical improvements come with breaking changes. We do not recommend trying to upgrade an existing Boilerplate-based project to Author Kit.
3. While Author Kit is based on very mature and very large projects, it's relatively young itself. As such, Author Kit is going through fairly rapid improvements. Getting changes from upstream may feel laborious.
4. Nearly all Adobe boilerplates are inspired by the original. As such, projects like Adobe Commerce, Universal Editor, AEM Forms, Dynamic Media, and more will be more work to port to Author Kit.
5. Author Kit can often be a place for researching early-access ideas. As such, if we find a feature is not adopted by the overall community, we will remove it. Some currently live examples: Schedules (promotions), Quick Edit, and Focal Point.