Storyblok

Overview

The SCAYLE Storefront Application includes a default integration that allows you to use Storyblok as a CMS. It provides various helpers to quickly introduce custom content into your Storefront Application. In the background, the Storefront Application uses @storyblok/nuxt. For further details, consult the Storyblok documentation.

Quick links

• Storyblok Developer Guides
• Storyblok Editor Guides
• Storyblok Youtube Walkthrough

Storefront Integration

Local Preview

You can preview your local development environment directly within Storyblok.

Product Data

To link content in Storyblok to your shop data, the Storefront Application adds fields in Storyblok that you can then fill with your desired categories and products.

Ready 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.

Base Storyblok Components

• Accordion
• AccordionEntry
• Banner
• BannerLink
• ClickableImage
• CmsImage
• CmsLink
• CmsText
• CmsVideo
• DetailImage
• Grid
• GridTile
• ImageSlider
• ImageSliderSlide
• ImageText
• Page
• Product
• ProductSlider
• ScrollableLinkList
• SlideShow
• Story
• StoryblokLink

Technical Details

The Storyblok integration with the Storefront Application is separated between local development (using Storyblok CLI) and shop runtime (using @storyblok/nuxt).

Initial Development Setup

To use Storyblok as your CMS, add the following configuration to your nuxt.config.ts:

Copy

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

The initial setup requires the creation of a dedicated local .env.storyblok file. This file will contain all Storyblok-relevant environment variables necessary for local development:

ini

Copy

STORYBLOK_PERSONAL_TOKEN=<INSERT-YOUR-TOKEN-HERE>
STORYBLOK_SPACE_ID=<INSERT-YOUR-SPACE-ID-HERE>

Additionally, ensure your nuxt.config.ts is configured to use the access token:

typescript

Copy

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

• Create a STORYBLOK_PERSONAL_TOKEN: A STORYBLOK_PERSONAL_TOKEN can be created as part of the Storyblok Account Settings.
• Source the STORYBLOK_SPACE_ID: The STORYBLOK_SPACE_ID can be found as part of the URL when logged into storyblok.com and accessing the appropriate Storyblok space.

Scripts

As part of the Storefront Application's package.json, some additional scripts are included to interact with Storyblok:

• storyblok:download: Downloads the latest component schemas from the respective Storyblok space using the Storyblok CLI.
• storyblok:generate: Uses the downloaded components JSON schema and transforms it into TypeScript types (see section "Type Definitions").
• storyblok:login: Authenticates your local development environment with the Storyblok CLI.
• storyblok:unused: Outputs an overview of used and unused Storyblok components in a space.

While storyblok:download and storyblok:login directly utilize the Storyblok CLI, storyblok:generate and storyblok:unused execute dedicated .cjs scripts (scripts/storyblok-generate.cjs and scripts/storyblok-unused.cjs respectively).

Type Definitions

• storyblok/types/storyblok.d.ts: Contains manual type definitions.
• storyblok/types/storyblok.gen.d.ts: This file is automatically generated by the storyblok:generate script based on the local Storyblok components JSON schema. The script uses a custom internal NPM package called storyblok-generate-ts, which provides a configurable transformation function (storyblokToTypescript) that outputs the type definition based on a pre-configured object.

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 storyblok:download and storyblok:generate scripts to fetch content schemas and update local types.

Basic Composables and Helpers

To simplify the usage of certain functionalities with Storyblok components, the SCAYLE Storefront Application includes a few reusable composables and helpers:

• storyblok/composables/useCmsAlignment.ts: Provides Tailwind-compatible alignment classes to be used with Storyblok components.
• storyblok/composables/useStoryblokImage.ts: Provides utilities to process and return a sanitized teaser image object for use with Storyblok components.
• storyblok/composables/useStoryblokMargins.ts: Provides Tailwind-compatible margin classes to be used with Storyfront components.
• composables/useCmsListingContent.ts: Returns a formatted object for usage with listings containing the CMS content, preListingContent, postListingContent, and hasTeaserImage.

Shop Runtime

The runtime integration between Storyblok and the SCAYLE Storefront Application is achieved by using the @storyblok/nuxt module.

The configuration can be extended under the storyblok key as part of the nuxt.config.ts. Refer to the official Storyblok module documentation for more information and configuration options.

The default configuration only sets the STORYBLOK_ACCESS_TOKEN and enables the bridge option. The bridge option is used for integrating with the Nuxt framework and with the Storyblok visual editor.

The integration additionally relies on the @nuxt/image module (See NuxtImage module documentation) to handle images used with Storyblok components.

Deployment Requirements

The @storyblok/nuxt module provides an integration with the Nuxt RuntimeConfig functionality. This means that the NUXT_STORYBLOK_ACCESS_TOKEN can be set during the application's runtime as an environment variable instead of during build time, enhancing deployment flexibility.

Auto-Imported Components

Storyblok components are auto-imported from the storyblok/ directory at the root of the project and are made available throughout the project. Be mindful of component name collisions: if your component in the ~/components directory is named the same as one inside ~/storyblok, there can be issues with the Storyblok auto-imported components. The StoryblokComponent is also auto-imported and can be used out-of-the-box.

Fetching Content

The Storefront Application provides a simple way to fetch content from Storyblok.

• useCMS Composables: The useCMS composable internally relies on the storyblok-js-client package to fetch content. As content from Storyblok allows references to data provided by SCAYLE (e.g., product data), the Storefront Application features this composable. useCMS accepts a key argument that will be used as a useAsyncData key for storing values.
  useCMS exposes the following two dedicated composables:
  • useCMSBySlug: Wraps an async function around useAsyncData and useStoryblokApi composables to fetch Storyblok content by slug (using the slug format cdn/stories/${slug}).
  • useCMSByFolder: Wraps an async function around useAsyncData and useStoryblokApi composables to fetch Storyblok content by folder (using the starts_with parameter).

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.

Example Usage:

typescript

Copy

import type { SbFooter } from '~/modules/cms/providers/storyblok/types'
import { useCMSBySlug } from '~/modules/cms/providers/storyblok/composables/useCMS'

const props = defineProps<{
  slug: string
}>()

const { fetchBySlug } = useCMS(`content-page-${props.slug}`)

const { data, error, status } = await useCMSBySlug<SbContentPage>(
  `content-page-${props.slug}`,
  `content/${props.slug}`,
)

Live Preview

To display unpublished changes on the initial load within the Storyblok editor, the access token needs the Preview access level. If the access token has a different access level, unpublished changes will only appear after modifications are made within the editor.

Components

This section offers a detailed overview of various shop areas utilizing Storyblok content, alongside their configuration options. It's essential to review the type definitions (storyblok/types/storyblok.gen.d.ts) to understand the optional values and the expected data types for each configuration option.

Homepage

Component: SlideShow

Component: Slide

Component: ImageSlider

Component: ImageSliderSlide

Component: Grid

Component: GridTile

• Options:
  • headline: accepts a string
  • cta: accepts a string
  • cta_link: accepts a link

Component: ImageText

Component: ProductSlider

Component: Banner

Component: Story

Footer

Component: Footer

Component: LinkGroup

Component: Link

Listing Pages

Component: ListingPage

Parameter	Details
teaser_image	Sbasset
teaser_image_mobile	Sbasset
pre_listing_content	SbAccordion | SbAccordionEntry | SbBanner | SbBannerLink | SbClickableImage | SbCmsImage | SbCmsText | SbContentPage | SbDetailImage | SbDoubleColumn | SbFooter | SbGrid | SbGridTile | SbImageSlider | SbImageSliderSlide | SbImageText | SbLink | SbLinkGroup | SbListingPage | SbPage | SbParagraph | SbProduct | SbProductSlider | SbShopableImage | SbSlide | SbSlideShow | SbSocialMediaLink | SbStory | SbTitle | SbVideo
SEO	Copy {
title: string
plugin?: string
og_image?: string
og_title?: string
description?: string
twitter_image?: string
twitter_title?: string
og_description?: string
twitter_description?: string
}
post_listing_content	SbAccordion | SbAccordionEntry | SbBanner | SbBannerLink | SbClickableImage | SbCmsImage | SbCmsText | SbContentPage | SbCustomerServiceInfo | SbDetailImage | SbDoubleColumn | SbFooter | SbGrid | SbGridTile | SbImageSlider | SbImageSliderSlide | SbImageText | SbLink | SbLinkGroup | SbListingPage | SbPage | SbParagraph | SbProduct | SbProductSlider | SbShopableImage | SbSlide | SbSlideShow | SbSocialMediaLink | SbStory | SbTitle | SbVideo

Service Pages

Component: Accordion

• Options:
  • has_link_list: accepts a boolean
  • entries: accept a list of SbAccordionEntry
  • margin_top: accepts a string

Component: AccordionEntry

Area: Content Pages

Component: Content Page

Parameter	Details
teaser_image	Sbasset
teaser_image_mobile	Sbasset
headline	String
subline	String
content	SbCmsImage | SbCmsText | SbGrid | SbImageSlider | SbProductSlider | SbSlideShow | SbSocialMediaLink | SbVideo | SbAccordion | SbCustomerServiceInfo | SbDoubleColumn | SbParagraph
SEO	Copy {
title: string
plugin?: string
og_image?: string
og_title?: string
description?: string
twitter_image?: string
twitter_title?: string
og_description?: string
twitter_description?: string
}

All Pages

Component: Video

Component: ClickableImage

Component: CmsImage

Component: CmsText

Component: DoubleColumn

Component: Paragraph