🔗 Contentful

Overview

Contentful is a headless CMS platform that you can use out-of-the-box with the Storefront Application. For more information on the features of Contentful itself, refer to the Contentful documentation.

Storefront Integration

Preview

Included Components

The following components are implemented as part of the Storefront Application, meaning they are available out-of-the-box for all shops that are built upon this foundation. You can explore all components in our UI Component Overview.

Core Content Primitives

TextComponent
LinkComponent
ImageComponent
VideoComponent

Interactive & Basic Content Blocks

AccordionComponent
AccordionItemComponent
ButtonComponent

Layout & Structural Components

PageComponent
ProductListingPageComponent
SectionComponent
GridComponent
DividerComponent

Rich Content

RichTextComponent

E-commerce Specific Components

SliderComponent

The power of this system lies in combining these base components to create more sophisticated e-commerce blocks. Here you can find some examples of how to build common page elements.

Additionally, the Contentful integration includes a ContentfulComponent, which takes a content element and automatically renders the appropriate component based on the specified component field in the content.

For a live, interactive preview of these components and their configurations, please refer to our Storybook component library.

Initial Development Setup

To use Contentful as your CMS, run the following command:

This command will prompt you to:

Select a CMS provider.
Provide the Contentful space ID, used to connect to the correct contentul instance.
Provide an access token, used to authenticate against the Content Delivery API.
Provide preview access token, used to authenticate against the Preview API within the Editor.
Provide a management access token, used to authenticate against the Content Management API when generate types and import the content model.
Specify whether the content model should be imported.

Importing the content model is only intended to be used with empty CMS spaces, as running it in spaces with existing content may cause issues with the existing content model.

After entering these details, the provider within nuxt.config.ts will be configured.

export default defineNuxtConfig({
    cms: {
        provider: 'contentful'
    },
})

Furthermore, the env vars CMS_PROVIDER, NUXT_PUBLIC_CMS_SPACE, NUXT_PUBLIC_CMS_ACCESS_TOKEN, NUXT_PUBLIC_CMS_PREVIEW_ACCESS_TOKEN and CONTENTFUL_MANAGEMENT_TOKEN in the .env file will be updated with the provided values.

Local Development Workflow

The process to synchronize a Storefront Application project during local development is identical for both new and existing projects. It primarily involves running the cms:sync scripts to fetch content schemas and update local types.

After synchronizing the types, you can update or create the component. Be sure to add new components to ContentfulComponent.vue to ensure they are rendered.

Shop Runtime Integration

The runtime integration between Contentful and the Storefront Application uses the contentful, @contentful/rich-text-html-renderer and @contentful/live-preview packages.

The integration additionally relies on the @nuxt/image module (see the Nuxt Image module documentation) to handle images used with Contentful components.

Live Preview

The Preview Delivery API is used during the initial load to display unpublished changes in the Contentful editor. To accomplish this, an additional preview access token is required. Without it, changes will only be visible after they are published in the editor.

To enable the preview token in your runtimeConfig, add the following to your nuxt.config.ts file:

To map content locales to their respective shops, define custom preview tokens. These tokens are used in the preview URL setup and consist of key-value pairs, where the locale serves as the key.

When setting up the preview URLs within Contentful, also add the query parameter ?_editorMode={entry.sys.updatedAt} to the URL. This action informs the site to bypass the cache and load Contentful's live preview SDK seamlessly.

Inspection Mode

To utilize inspection mode, ensure every CMS component includes the data-contentful-entry-id and data-contentful-field-id attributes on the component's root element. Set data-contentful-entry-id to the sys ID of the content element and data-contentful-field-id to the field name to focus on when the Edit button is clicked in the editor.

Deployment Requirements

Our implementation provides integration with the Nuxt RuntimeConfig functionality. This means that NUXT_PUBLIC_CMS_SPACE, NUXT_PUBLIC_CMS_ACCESS_TOKEN, NUXT_PUBLIC_CMS_PREVIEW_ACCESS_TOKEN and CONTENTFUL_MANAGEMENT_TOKEN can be set during the application's runtime as environment variables instead of during build time, enhancing deployment flexibility.

Fetching Content

The Storefront Application provides simple ways to fetch content from Contentful.

useCMSBySlug: Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug (a user-friendly and URL-friendly string used to identify content) limited to a single entry.
- The Contentful entry you are fetching must have a slug field and value that matches what you are trying to fetch.
useCMSByFolder: Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug (a user-friendly and URL-friendly string used to identify content) for a folder.
- The Contentful entry you are fetching must have a slug field and value that starts with the slug you want to fetch.

Default Options for Contentful API

Both useCMSBySlug and useCMSByFolder functions are configured with the following default options for the Contentful API:

language: Matches the current shop's locale.

Whenever the _editorMode query parameter is present (inside the CMS Editor) and the allowDrafts config is true, the contentful API client is configured to use the previewHost and previewAccessToken to connect to the Content Preview API instead of the Content Delivery API.

As these composables wrap useAsyncData, they inherit its full type signature. For more details on all returned data, refer to the Nuxt documentation on Data Fetching.