Building a headless frontend for Bloomreach CMS
Tags: headless, bloomreach, cms, frontend
Published: 2021-06-04 15:06:06

In the last six months I was working on a headless frontend coupled with Bloomreach. These are some of my observations and experiences.

It’s quite easy from a front-end perspective to get started with the [Bloomreach Software Development Kit](https://www.npmjs.com/package/@bloomreach/spa-sdk) that they developed for a headless implementation. This SDK makes it easy to get started with a simple component library. But some components you want to make will be complex. The Page Model API has a couple of limitations if you want to build complex components.

## The Bloomreach Page Model API
From an architectural principle the [Page Model API or resource API](https://documentation.bloomreach.com/14/library/concepts/page-model-api/introduction.html) is well built. Every page has a JSON object with all the data you should need. If you have multiple resources on a page, only one reference to that object is published in the Page Model API. This has the benefit that no double data is present.

It is beneficial that not the whole page structure is represented. You can, for example, simply reorder components. A side note is that you can add some fixed components with Bloomreach, like a menu or footer that you want to show on every page. But these extra components will not automatically be present in the correct order.

A limitation or feature of this system is that it is kinda impossible to have recursive content or loops. If your content looks like recursion Bloomreach will send you a unique identifier. This means that you may need to build an API endpoint to fetch some data a bit later. The documentation only speaks about defaultMaxContentReferenceLevel 1,2 or 3 so I presume you don't want to go higher.

A concrete example of this limitation is a FAQ document with FAQ items. In these items it is possible to have other documents to create your page. These documents can create a loop so the Page Model API will return only a unique identifier.

## Images in Bloomreach
The default way to manage images with Bloomreach is a bit limited. The Page Model API will always return all urls of all the image variants. Furthermore, there is no default way to get heightly optimized images. Bloomreach does not support [WebP](https://web.dev/uses-webp-images/) or [AVIF](https://netflixtechblog.com/avif-for-next-generation-image-coding-b1d75675fe4) encoded images for example.

I personally like to query images so that I can specify the size, format and resolution to create truly [responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).

From a front end perspective this is quite a bummer although you could also use a dedicated image CDN that you can couple with Bloomreach that will support all modern features.

## Statically generating pages
Every Page Model API request you make gets a response. For a non existing page you get the default page not found template but there is another option. If you load the front end inside the Bloomreach Experience Manager, a special request is made with a Json Web Token which enables the preview version of a page.

So depending on what environment your front end is loaded you get different responses. There is also no default event you can track when a page is published. So it is impossible to know when a specific page needs to be built.

## Developer experience
You get all the pros and cons of a headless frontend. The Bloomreach SDK is a bit opinionated so you will write some boilerplate code for every component. But the biggest advantage is that you can couple your local front end to every Bloomreach backend. If you have a backend component library you can reuse them, if you have a whitelabel front end library you can reuse it too.