Contentful

Introduction

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

Storefront Integration

The Contentful integration with SCAYLE Storefront Boilerplate can be separated by concerns of local development (using contentful-cli) and shop runtime (using contentful Delivery API).

Initial dev setup

The initial setup of Contentful within the SCAYLE Storefront Boilerplate requires the creation of a dedicated local .env.contentful file. The local .env.contentful will contain all Contentful-relevant environment variables to be able to work Contentful Management API.

Copy

CONTENTFUL_MANAGEMENT_TOKEN=
CONTENTFUL_SPACE_ID=

Create a CONTENTFUL_MANAGEMENT_TOKEN

A CONTENTFUL_MANAGEMENT_TOKEN can be created as part of the Contentful account settings. For more information on creating your Contentful management token, see here.

Source the CONTENTFUL_SPACE_ID

The CONTENTFUL_SPACE_ID can be found in general settings once you are logged into Contentful. For more information on finding your Contentful space ID, see here.

Scripts

As part of the Storefront Boilerplate package.json, some additional scripts are included to interact with Contentful.

contentful:download

• Downloads the information from Contentful
• Uses contentful-export to download all data from the respective Contentful space. You can modify it as needed.
• Data will be stored in contentful.{SPACE_ID}.json inside the root dir of your app.

contentful:generate

• Running this command will give you all type definitions from your contentful.{SPACE_ID}.json as well as some type guard functions
• Uses cf-content-types-generator to generate types
• This will be generated inside of ./modules/cms/providers/contentful/types/gen

Type Definitions

Manual type definition:

• ./modules/cms/providers/contentful/types/contentful-defs.d

Generated type definition:

• ./modules/cms/providers/contentful/types/gen/*

Shop Runtime Integration

The runtime integration between Contentful and Storefront Boilerplate uses the Contentful Content Delivery API.

To use Contentful with Storefront Boilerplate, we need to set the CMS provider to Contentful:

typescript

Copy

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

To have access to the Contentful Content Delivery API, we need to provide an accessToken and spaceID. We'll define it like so:

Copy

NUXT_PUBLIC_CMS_ACCESS_TOKEN=
NUXT_PUBLIC_CMS_SPACE=

After adding environment variables to your .env, your integration is complete. You can also modify your accessToken and spacein runtimeConfig like so:

typescript

Copy

export default defineNuxtConfig({
    runtimeConfig: {
        public: {
            cms: {
                accessToken: '', // Overide: NUXT_PUBLIC_CMS_ACCESS_TOKEN
                space: '', // Overide: NUXT_PUBLIC_CMS_SPACE
            },
        },
    },
})

The integration additionally relies on the @nuxt/image module (see the NuxtImage 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, unpublished changes will only be visible after they are published in the editor.

typescript

Copy

export default defineNuxtConfig({
    runtimeConfig: {
        public: {
            cms: {
                accessToken: '', // Overide: NUXT_PUBLIC_CMS_ACCESS_TOKEN
                previewAccessToken: '', // Overide: NUXT_PUBLIC_CMS_PREVIEW_ACCESS_TOKEN
                space: '', // Overide: NUXT_PUBLIC_CMS_SPACE
            },
        },
    },
})

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

Deployment Requirements

Our implementation provides integration with the Nuxt RuntimeConfig functionality. This means that the NUXT_PUBLIC_CMS_ACCESS_TOKEN, as well as NUXT_PUBLIC_CMS_SPACE be set during the application's runtime as an environment variable instead of during build time.

Auto-imported components

Contentful components are auto-imported from the ~/modules/cms/providers/contentful/components directory so components are made available throughout the project. To be mindful of component name collisions we added the prefixCMS to every component .

Ready Components

The following components are implemented as part of the Storefront Boilerplate, which means they are available out-of-the-box for all shops that are scaffolded from the Storefront Boilerplate - that is, all SCAYLE shops.

Base Contentful Components:

• Accordion
• AccordionEntry
• Banner
• BannerLink
• ClickableImage
• Image
• Link
• Text
• Video
• DetailImage
• Grid
• GridTile
• ImageSlider
• ImageSliderSlide
• ImageText
• Page
• Product
• ProductSlider
• ScrollableLinkList
• SlideShow
• Story
• ContentfulLink

The current implementation will add 'CMS'prefix to every component so when you are using components inside of a template you should use:

html

Copy

<CMSImage
...(props)
></CMSImage>

Default usage within Storefront Boilerplate

The following section contains an overview of all shop areas, that use Contentful content and their options.

For an actual reference which values are optional and what value types are expected for each option, check the type definition!

Fetching content

Storefront Boilerplate provides simple ways to fetch content from Contentful.

useCMS()

As content from Contentful allows references to data provided by SCAYLE, for example product data, Storefront Boilerplate features the useCMS composable. This composable internally relies on the contentful package to fetch content from Contentful.

An example usage for getting relevant content might look as follows:

Copy

const {
  data, status,
} = useCMSBySlug<TypeContentPageSkeleton>(
  `content-page-${props.slug}`,
  {
    content_type: 'contentPage',
    'fields.slug[match]': `content/${props.slug}`,
  },
)

The composable exposes the following data and functions as dedicated composables:

• useCMSBySlug
  • Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug using the slug format - user-friendly and URL-friendly string used to identify and reference a specific piece of content.
  • NOTE: Entry you are fetching must have field slug and value that you want to fetch
• useCMSByFolder
  • Wraps around Nuxt's useAsyncData function using the contentful package to fetch Contentful content by slug using the slug format - user-friendly and URL-friendly string used to identify and reference a specific piece of content.
  • NOTE: The Contentful entry you are fetching must have a slug field and value that starts with the slug you want to fetch.
• defaultCMSOptions
  • Returns default options for fetching options locale, env, etc.

Composables

Basic composables and helpers to simplify the usage of certain functionalities with Contentful components.

Storefront Boilerplate includes a few simple reusable composables and helpers:

useCMSAligment()

Provides Tailwind-compatible alignment classes to be used with Contentful components

useContentfulImage()

Provides utilities process and return a sanitized teaser image object to be used with Contentful components

useContentfulMargins()

Provides Tailwind-compatible margin classes to be used with Contentful components

useCMSListingContent()

Returns a formatted object for usage with listings containing the CMS content, preListingContent, postListingContent and hasTeaserImage

Components

The following section contains an overview of all shop areas, that use Contentful content and their options.

For an actual reference which values are optional and what value types are expected for each option, check the type definition!

Homepage

Component: SlideShow

Component: Slide

Component: ImageSlider

Component: ImageSliderSlide

Component: Grid

Component: GridTile

Component: ImageText

Component: ProductSlider

Component: Banner

Component: Entry

Footer

Component: Footer

Component: LinkGroup

Component: Link

Listing Pages

Component: ListingPage

Service Pages

Component: Accordion

Component: AccordionEntry

Content Pages

Component: Content Page

Parameter	Details
uid?	string
teaserImage?	Asset
teaserImageMobile?	Asset
headline?	string
subline?	string
content?	Copy Array<TypeAccordionSkeleton

Copy

  | TypeCmsTextSkeleton
  | TypeDoubleColumnSkeleton
  | TypeGridSkeleton
  | TypeImageSkeleton
  | TypeImageSliderSkeleton
  | TypeParagraphSkeleton
  | TypeProductSliderSkeleton
  | TypeSlideShowSkeleton
  | TypeSocialMediaLinkSkeleton
  | TypeVideoSkeleton>

| | seo? | TypeSeoSkeleton |

All Pages

Component: Video

Component: ClickableImage

Component: Image

Component: Text

Component: DoubleColumn

Component: Paragraph

Component: settings - tracking

Component: settings - margin

Component: settings - seo