Integrating Rich Text segments and microcopy from Contentful into your React app
Just like microorganisms in the real world living unnoticed all over the place, your application’s UI is filled with tiny bits of content. For example, you might have phrases like, “Something went wrong with application,” and, “Sure, go ahead and save cookies,” (e.g. microcopy) as well as bigger segments — for instance, a few paragraphs and an image that you use to explain how your recommender engine works.
Should you store all these things in Contentful? Probably not. To elaborate, the right strategy depends on how involved content editors need to be in changing the words that appear on your site. For small- to medium-sized operations, it’s unlikely editors will need to be able to manage shorter interface text. They’ll likely just ask a developer to change it, which is totally fine. But there might be some segments on the page that they want to update without having to bring in a developer.
In this post, I will outline some content modeling and code examples for answering the question of how to bring content from Contentful into your React app, right where it is needed.
Questions about your content
So how should a team decide which types of content they need to model and house in Contentful? Here are a few things to consider:
Does the content need to be managed directly by the marketing team without a developer doing a commit?
Is the content Rich Text, e.g. markup like lists, or images?
Does it need some kind of publishing workflow?
Do you need to maintain translations of your content into multiple languages?
If a use case meets two or more of these requirements, you should strongly consider storing it in Contentful. Rich Text loves to be in Contentful, unless it never needs to change, in which case a developer can just write it as a React component. It’s those editor-managed, workflowed, rich text blocks that would really benefit from having a slot in Contentful.
Every team is different though: there’s nothing stopping a team from moving even shorter interface strings to Contentful if there is a motive to tweak them a lot for experiments or other purposes like allowing non-developers to provide translations.
Modeling keyed Rich Text content
There’s a pretty generic pattern that you can use to make segments of Rich or plain text available to your app’s frontend. I call it the “Keyed Rich Text” pattern:
Give it a human readable key that a developer can use to address it.
Give it an administrative title that will help you remember what it is on the backend.
Add a Rich Text field to hold the content itself.
In Contentful, it will look something like this:
Or, as seen in the editing screen:
I would advise against making the key field a slug that depends on the admin title. If you change the admin title, by default, the slug will also change.
Another nice thing you can do with the key is give it a “prohibit” pattern to encourage people to use names that look like variables. Inside Content Model > Keyed Rich Text > Key > Settings, you can do:
If you want to prohibit capital letters as well, the regex is [\sA-Z]. We JavaScript developers like to camel-case things though, so I would keep it to allow capital letters in the key.
You can create a plain-text variant of this content type if you only want to model true “microcopy.”
Bringing keyed Rich-Text content into the frontend
It’s pretty easy to get one or more pieces of keyed content into your app. Here are some functions that you can use for getting either a single piece of content, or multiple at once:
The access token needed is the Content Delivery API access token, found at Settings > API Keys > [Your API key] > “Content Delivery API - access token”. This article isn’t focused too much on security, but remember that this token will grant read-only access to all of your content! If possible, you may want to use the token only during server-side rendering, and add it as a process.env variable so that you don’t have to commit it.
Rendering strategies
That brings us to the last few pieces: where do we call our function to get the content, and how do we render it?
A lot of this depends on your existing app rendering strategy, and how many pieces of Rich-Text content like this you have on a page. If your app does everything client-side, you can call for the content in the browser. If you can do server-side rendering, that can be a good move to reduce things shifting on the page, or having to provide “skeleton” components to fill space in the meantime.
Either way, I recommend getting multiple entries at once using something like the getKeyedContentMultiple function shown above.
When you’ve got your keyed Rich Text entry, or entries, loaded and you want to render their contents, I highly recommend using the documentToReactComponents function from the contentful/rich-text-react-renderer package. This will render your Rich Text field content for you, and also let you define your own React components to use for any type of markup found in the Rich Text field.
Here is an example:
To use this in a component, you can say:
Wrapping up
Web app interface content requires tweaking some of your modeling strategies, as opposed to sites where all content is addressable by a particular URL. I hope you can all use this guide to give your organization’s editors control over the content that they need to manage, while keeping your frontend code streamlined and maintainable.
