Using AEM with Edge Delivery Services

It’s free to use, but who knows for how long?

Adobe has been pushing us at Blue Acorn towards AEM Edge Delivery Services for a while now, back even a year or two ago when it was codenamed Franklin and Helix, Adobe was tirelessly pushing it as the future of the platform. While the licensing for it is still somewhat murky, The Experience League has recently published some articles outlining how to use it generally complete with instructions on how to configure it with several CDN services. From all outward appearances, it seems AEM with Edge Delivery Services is free for personal-ish use and is becoming a flagship AEM offering.

Selfishly, I’ve been meaning to start publishing a bit more, and would normally look towards a static site generator like Hugo or Gatsby hosted on Github Pages - a free and practical way to host a personal site that can be paired with markdown editors to provide a fairly nice, if not a bit technical, writing experience. But after spending months telling people about how document-based authoring is the future, and the virtue of 100% lighthouse scores, all this newfound documentation outlining how to leverage it for free was too enticing. I just went for it and set up this blog using AEM’s document-based authoring. It’s pretty interesting, let me walk you through it.

Nomenclature

First, let me start with the nomenclature. As I mentioned, Adobe is now calling this just straight-up AEM. For example, this blog has a project repo on github, and it’s forked from a repository named `aem-boilerplate` which used to be the Franklin Boilerplate; this renaming to AEM signals the significance of this. If you look at the Experience League, they are referring to this setup now as AEM directly, and under the banner of “AEM with Edge Delivery Services”. Internally, we’ve been calling AEM Sites and Guides “AEM Classic”. I’ll probably stick to that here, start building the habit.

How it works

So take the AEM Boilerplate repo and fork it, walk through a few steps and end up with a Google Drive Folder that effectively serves as your content management system. When paired with the AEM Sidekick, available for Safari and Chrome, it lets you easily preview and publish content right from the browser.

In all honesty, it still has its bugs, but it does deliver on the Content Supply Chain promise of using the best tool for the job. I’m not writing this in some admin panel, I’m writing this in Google Docs. When I’m done, I’ll press a Preview button in Docs and see it live, and press a “Publish” button and it’ll go live. It really is that simple, and nothing else is really doing that yet.

The closet thing I’ve seen is the Gatsby Plugin that enables Google Drive support. Just scroll through that briefly, look how much more complicated that is to configure than what I did in the last paragraph. Not only that, but you have to sort out hosting and build a project that leverages the plugin. AEM is just simpler, and nowhere in Gatsby’s documentation does it cover how to maintain a perfect lighthouse score.

The conceit with Edge Delivery is that its content delivery model is obnoxiously simple, almost to the point of questioning if it’s good enough for real world use. If you consider Gatsby or Hugo, the project repo basically represents a theme, blocks, content, images and all concerns to build the site. An AEM project has some of this, but it strips a few things away.

Blocks

Content, obviously, is stored in Google Drive, Sharepoint, or some other means, so that falls away. Often, you’d see stuff like Footers and Navigation bars managed through layouts or something, but AEM has some expected docs `nav` and `footer` which get converted to HTML and sandwiched between content. Your task is to take the converted HTML and style it and manipulate it. In essence, AEM Boilerplate gives you a head file to include if you want to add anything arbitrary, but everything else is just compiled and served out. While technically you can use this to add a framework, they caution against it as they add bloat and could prevent the 100% lighthouse score.

So if you look at how blocks work, you’ll see they are simple; a stylesheet and a single javascript file. When generating HTML from a cloud share, when AEM comes across a table whose top row contains a string, it will invoke the CSS and pass the rendering through the block javascript. The goal at this point, in the javascript file, is to take the table contents and figure out which is what, and based on that build the DOM you need and inject that into the page.

Other than blocks, there’s really not very much else in a project repo. There’s some utility scripts, global styles, a font directory, and a few other things. The `icons` directory is interesting, svg files within this directory act as shortcodes. You can see this in the navigation, where I can place a by placing the word blueacorn between two colons.

helix-query.yaml

One other file of note is the helix-query.yaml file, which is another bizarre yet reasonable approach to managing metadata. So this file describes how AEM indexes the pages it creates, wherein you define the attributes you want to track (title, last modified, description, that kind of thing) and then how it can fetch this data. On the backend, AEM populates all the popular metadata tags, and this file basically describes how to navigate the DOM structure to fetch it. This gets used during publishing a document, as AEM will use this metadata to build an index and store it to, you guessed it, a spreadsheet within your cloud storage.

query-index.json

This data gets exposed through a json file https://doughatcher.com/query-index.json and then you can use it to build additional interfaces. So when I wanted to use this as a blog, and there didn’t seem to be a way to automatically fetch my posts for the homepage, I was quickly able to rig this up and build a blog block that builds the cards on the homepage. It’s simple and effective, and not really big enough to warrant any more complexity.

Adding Comments

You probably notice there are comments at the bottom of the page. This is using a pretty common technique, where I just embed a disqus comment block into the page. The technique for accomplishing this is a little odd in this case, because in most static site generators like Gatsby or Hugo, we’d have some layout page that would represent the body of the content page, and we could reference a layout file with the disqus code we needed.

In AEMs case, they really just give you a scripts.html file, and this file is expected to be included in a head tag. In my solution, I took the disqus universal embed, and added it to an onload listener, and inject the div that the disqus embed grafts to into the appropriate spot into the DOM if the page’s path isn’t /. Pretty simple, and I should probably change it to look for /pages, but these are things that can be added over time.

Search

You’ll notice that there is no search here. In my travels, I think there’s actually a decent search block that doesn’t seem too hard to implement. Important to note that the AEM Boilerplate has a search icon, but it’s not linked to anything and it’s on you to implement.

AEM Sidekick

The other major thing to note is how pervasive AEM Sidekick seems to be. It’s in the iOS App Stores, has a Safari Extension and full Google Chrome support where it seems to be the best supported. So far, it’s mostly worked everywhere I’ve tried to use it. The sidekick itself feels a bit primitive still, but it’s a great effort.

Going Live

So, once I rigged it all up, getting my domain pointed to it was another simple and well-documented affair. Turns out, the Experience Leage has public documentation detailing how to set it up with most major CDNs, including my beloved Cloudflare. In my case, the trick involves setting up a CNAME to my hlx.live domain, and configuring a Cloud Worker which proxies the data from hlx.live to my domain with some caching configuration to make it all work, Pretty easy, no worse than setting up any other hosting service.

Conclusion

I think Adobe’s target audience here are enterprise customers looking for a really simple distributed editing model and insane performance at high load and scale, but that doesn’t mean it’s not a decent little free blogging platform. So far it’s proven to be quite capable, and delivers on it’s promises on ease-of-use and so-fast-its-a-gimmick performance guarantees. I will say it’s still a little rough around the edges, but I’ll use it until the kick me off the service!