Getting started with Contentful Studio and the Experiences SDK
Contentful Studio is designed to streamline content management and collaboration processes. It offers a drag-and-drop interface for building content, defining relationships between content, and configuring rich text fields, images, banners, and other promotional items commonly found in online content. These are called Experiences.
Experiences are the various ways in which content can be delivered to end users across different channels and devices. This includes websites, mobile apps, voice assistants, smartwatches, and any other platform where content is consumed. Experiences are created by defining content models, structuring content, and then delivering it through APIs to these various channels.
Key features such as real-time collaboration, version history, and content previews — which empower teams to work efficiently and iteratively on content projects — emphasize Studio's flexibility, enabling customization to suit different workflows and project requirements.
While this is great from a collaboration and marketing perspective, a developer needs to implement the Experiences SDK. In this article, we’ll share how developers can fully understand the process for getting started with implementation as well as standing up an entire project that will be ready for production.
What developers will learn in this post
We are going to explore two very integral flows that most developers implement:
Implementing a design system that gives UI the same functionality and feel across applications, web pages, and devices.
Creating reusable patterns and components that will allow your team to hand off the building process to non-technical people so they can continue to build their landing pages, promotions, and other materials.
Getting started
Before you start setting up the Experiences SDK, you will need to ensure that Experiences is enabled in the Contentful web app:
Developer or Admin access to a space,
To learn more about the Experiences setup steps, refer to What are Experiences?
Once you have Experiences set up in your desired space, there are a few things to note on the technical side:
Currently, the SDK only works with React applications (React v18+).
The SDK requires the Contentful SDK v10.6.0 or newer, which is a peer dependency.
Your web application must support being rendered in an iframe. The iframe is used for the editing experience but not when displaying the experience on your site. If you have a CSP policy blocking this, you must include https://app.contentful.com into the list of allowed domains.
Installing the SDK
To get started, create a new React Application. An easy way to create a new React App is to use the Create React App tool which will help you spin up an app.
Next, install the Experiences SDK. Below is a command using npm but you can install the package using the package manager of your choice.
Creating a component
Let’s start by creating a simple branded button component which will show up in the Experiences editor that users can choose to drag and drop into their layouts.
In our code, we’ve created a blue button. But how do we let Contentful Studio know that this button can be used and duplicated for use in pages and layouts?
Registering a component
To register our button so that Contentful can pick it up, we will want to use the Experiences SDK and call the defineComponents method which will allow us to specify how the button is named when it shows up in the Contentful Studio interface.
Notice here in the variables section, we are able to pass the prop text which will come from user input via the Contentful Studio interface. This will allow our users to specify what the text of the button should be.
Component schema helps define how the components interact and what kind of values they can handle. We have documentation on our full schema so you can get familiar with all the different values you can use.
But what if we want to allow users to select a variety of button styles and use our brand style guide and UI? Next comes defining design tokens.
Defining design tokens
Design tokens are simply values that can be defined via the SDK and which can then be used in the Content Studio interface.
Design tokens contain information about things like text color, text size, font family, padding, etc. Many of us work with design teams that have spent a lot of time refining the brand’s design and as developers we want to ensure that the people using Contentful Studio for creating layouts that will go to production do not stray away from these guidelines.
Design tokens are easy to implement and will automatically show up in the Contentful Studio interface when they are registered using the SDK. An example of registering tokens would look like this:
Here we use defineDesignTokens to create an object of styles. Note that it is possible to give custom names to styling such as color: { Slate: ‘#94a3b8’, ... }. Here, when a user chooses “color” in the Contentful Studio interface, they will be presented with a dropdown list of colors by name like so.
Example: Line height
Example: Font size
Example: Colors
These key properties on the object will be a custom name of your choosing that can help identify well-known design tokens within your design system. Although design tokens resemble CSS attributes, only certain tokens are allowed.
To see a full list, refer to our design token documentation. You can also check out our deep dive explanation on design tokens.
Putting it together
So, now that we have a registered component and some design tokens, how can we merge the two together to allow for a button component that is fully customizable by the user inside of the Contentful Studio interface?
Let’s look at a Create React App example that will show how we can render our custom components and styles. We are going to use a React component that is provided by the Contentful Experiences package called ExperienceRoot which marks the place where users will be able to edit using the Experiences. With ExperienceRoot, you have the flexibility to enable users to build entire pages or only allow them to modify a specific portion of the web page.
ExperienceRoot will render the layout and content that was built inside of Contentful Studio. Since it is a React component, you can manage where it is rendered. For example, you ensure that your company footer always shows under the Contentful Studio content like such:
ExperienceRoot can be placed anywhere a React component can be placed as long as it makes sense according to the layout.
Finding the right experience ID
It is important to note that different experiences will have different IDs or slugs. In some cases, you may know the ID or slug but in other cases where you need to programmatically find them, the Experiences SDK allows you to fetch them.
The SDK package provides helpers, such as the useFetchBySlug hook to fetch the experience by its slug (configured in the settings tab for the experience) or the useFetchById hook to fetch the experience by its ID. The hook returns the experience object, which can be rendered with the help of the ExperienceRoot component. In the example above, we used useFetchBySlug to find the correct experience.
Previewing the experience
When previewing the experience in Contentful Studio, it shows your app inside an iframe. This means that it has to know a URL of the server, which hosts your web app, in order to render it on canvas in the iframe for content authors to be able to preview what they are building. The URL to your app must be configured via the Preview Configuration and must apply to the ExperienceType. To see existing preview configurations, refer to the "Content preview" menu of the "Settings" in our web app or make a CMA request.
Wrapping up
At this point, you should have a functional experience. Building and registering more components will enable authors to create layouts and pages within Contentful Studio, which will allow them to create the content they need while maintaining the correct design usage.
If you are using a platform such as NextJS, we have a technical guide for continuing the journey in our docs. It is important to remember that Experiences must have access to load within Contentful that way authors can see the preview of what they are building before it is built.
If you are troubleshooting your application, consider checking the connection to your server, the CSP policy, and the URL of your app. For a more technical dive into the SDK, check out our Experiences SDK documentation.
Looking for more resources on getting started with Contentful Studio? Visit the learning center and enroll in one of our live guided training sessions for developers and authors.
