🔗 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

Preview

You can preview your local development environment directly within Storyblok.

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 Storyblok integration includes a StoryblokComponent, 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 Storyblok as your CMS, run the following command:

This command will prompt you to:

Select a CMS provider.
Provide the Storyblok space ID, used to connect to the correct Storyblok instance.
Provide an access token, used to fetch content.
Provide a personal access token, used to generate types and import the content model.
Specify whether the content model should be imported.\

{% hint style="info" % } 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. {% endhint %}

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

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

Furthermore, the env vars CMS_PROVIDER, NUXT_PUBLIC_CMS_SPACE, NUXT_PUBLIC_CMS_ACCESS_TOKEN and STORYBLOK_PERSONAL_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 components. Be sure to add new components to StoryblokComponent.vue to ensure they are rendered.

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

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.

To fully utilize the Live Preview, ensure each component applies the v-editable directive to the root element.

Configuring the Visual Editor's Base URL

To set up the Visual Editor, you need to configure the base URL under the Space "Settings" page. For shops that use paths and language prefixes, be sure to include them. For shops with separate domains, simply enter the full domain.

When you view a Story in the editor, Storyblok will automatically append the page's slug to the URL, ensuring the correct page is displayed.

Deployment Requirements

The @storyblok/nuxt module leverages Nuxt's RuntimeConfig, which allows options to be set as environment variables during runtime instead of build time. This provides greater flexibility during deployment.

Fetching Content

The Storefront Application offers two simple composables for fetching content from Storyblok:

useCMSBySlug: Wraps an async function around useAsyncData and useStoryblokApi composables to fetch a single Storyblok story by calling storyblokApi.getStory(slug, defaultOptions).\
useCMSByFolder: Wraps an async function around useAsyncData and useStoryblokApi composables to fetch multiple Storyblok stories by calling storyblokApi.getStories({...defaultOptions, starts_with: folder}) \

Default Options for Storyblok API

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

language: Matches the current shop's locale.
resolve_url: Set to url.
version: Defaults to published. If the _storyblok query parameter is present (inside the CMS Editor) and the allowDrafts config is true, the value changes to draft.

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.