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 container 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.

In Author Kit, the only classes that get applied to a top-level section are the ones authors add. Additionally, the "container" elements directly below sections are gouped by either default-content or block-content. For block-content these will default to be full-width which is also different from AEM Boilerplate. This means blocks do not have to unset default styling as their first order of business.

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 (heros, etc). As such, placing all section styles in styles.css and putting optional section-metadata 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?

Author Kit tries to align to common industry conventions. In the wild, most design systems treat "card" as a singleton.

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?" there is a tradeoff here. You will end up making more table-based blocks if you have many authored cards. If you find you're making too many tables or you prefer to have a "cards" block, you can always make one.

Keeping consistent pluralization patterns for authors helps with discoverability and reduces training. This goes hand in hand with keeping a leaner and more maintainable codebase. The way you organize a series of card blocks is the exact same way you handle a series of teaser(s), carousel(s), and more. Structurally, keeping these the same will require fewer mental hurdles when writing layout code in 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 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 has been created based on lessons learned from many real-world projects.

Is Author Kit slower than Boilerplate?

Both projects are incredibly fast, but there are some limited scenarios where Author Kit can actually be faster. This has a lot to do with 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 and removed, fewer data attributes, fewer synthetic blocks, etc.
4. Functional / modernization optimizations: 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.
6. Because Author Kit provides more structure and extensibility points, as your project grows in complexity, you are less likely to write code in a way that could negatively impact performance.

Am I losing any functionality?

Author Kit prides itself on having a lot of 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 hero auto 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 and radical features 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 mature and 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. This can make moving features more work up front.
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.