"i only speak liquid" #40: Going Headless: Connecting a external CMS: Contentful

Hey all 👋!

Welcome to my 4th & final edition of 'i_only_speak_liquid'. I’m Luke, an expert on Storetasker and I love working on headless challenges within Shopify.

In January, another fellow Storetasker expert / Shopify dev will be taking the pen for 4 fresh edits 🙂 

What I’ve been thinking about:

I’ve been thinking about what to write for my final newsletter for Storetasker and settled on the final piece of the puzzle - content management systems. 

Shopify is getting better at being able to add custom data through metaobjects but it might still not be enough for some users. This is why a lot of headless stores will use an external service to manage their content outside of products and inventory. 

One popular service is Contentful which is a paid for service, but I’ve found it one of the nicest to work with. If you are looking for a free alternative have a look at Strapi which you can self-host.

Setting up for Contentful

The first thing we need to do is set up our Contentful client in our Remix space.  This is done much like the storefront API for Shopify. We head into our server.ts file and we can put our new code below the init for the Shopify API. This is just a preference as it keeps the external services together.

If we expand our Contentful function we can go into more detail around how it is set up.

First we set up the url that we need to hit. This requires us to set some ENV variables. These will later be set in the Hydrogen channel inside the Shopify admin but for local testing you can put them in your .env file locally.

We’ve set up these two ENVs that we must use for the api to work.

CONTENTFUL_SPACE_ID - the space in contentful you want to use.

CONTENTFUL_ACCESS_TOKEN - the access token that you can generate in the Contentful admin which gives you permission to the instance. 

You could also set up something like CONTENTFUL_ENV so that you can target Contentful environments that you can set up in their UI which are useful for testing content or for having separate content tied to a staging site. 

If you wish to use this you can update the URL to be https://graphql.contentful.com/content/v1/spaces/${env.CONTENTFUL_SPACE_ID}/environments/env/${env.CONTENTFUL_ENV}

The last thing we need to do before we can use it in our loader is to add the Contentful variable to the Remix context. This is inside the createRequestHandler and inside this is the  getLoadContext where we add our new variable. You’ll find this in the same file, server.ts. 

Now we’ve done that we can finally use the Contentful API in our loaders.

In our loader we just add the contentful parameter to our context deconstructing and from here we can use it to make a GraphQL call.

Say we have collection data inside Contenful then we can use our new api to call contentful and pass in our GraphQL query along with any variables.

To give you a full example, our query might look like this. It’s nice to have your queries in their own files exported as const for organisation and code readability, but you can also write them directly in the query parameter if you like. Here’s an example of it as a const variable in another file.

Note: if we have a content modal called Collection, in Contetnful’s GraphQL, the collection is also a collection of “collections” so the schema is collectionCollection. To make it easier, you can install the GraphQL explorer app in your space to test queries etc.

Finally, once we have the data back from the api after awaiting the response we can just return it like usual using Remix’s json() method like so:

3 links you can’t miss:

Contentful GraphQL intro - the intro into using their api and part of what we do in here.

Contentful preview mode - a useful param to now, as preview content is not always returned by the api.

Strapi - an open source self-hosted option like Contentful if you want more control or a free alternative.

1 app I like:

Boost AI Search & Filter - if I am not working on a headless site and the Shopify store wants better search functionality then this app is usually my go to.

It’s easy to set up and has decent customisation options for a developer to be able to tie into it. 

One learning as a freelancer:

Your time as a freelancer is important, so tracking how much you work on something should be important as well. 

Whether you bill hourly or per project I still think it is useful to know how much time you’ve spent on something. For this reason, I like to use an app called TopTracker.

You install it on your machine, and it just counts time and you set a note for each “timer”. It is not super complex or has 100 features, but uploads to the cloud, has some reporting and you can break down stuff by client and most important - it is free.

How you use it is up to you but it is great to look back on a month and see how much you’ve accomplished or use it for billing like I do. It can also be a great way of seeing time spent on the most profitable clients or vice-versa. 

Stay in touch!

Luke