docs

CMS

Your editors build the homepage, content pages, and category page content in a headless CMS, and the Storefront Application V3 renders it without a code change. It includes integrations for Storyblok, Contentful, Contentstack, and Amplience behind one provider contract, plus a local placeholder provider, so a new project runs before you connect a CMS.

Why it matters

A storefront mixes commerce data with editorial content such as a homepage hero, a category teaser, or a seasonal landing page. Editors change that content in the CMS and publish it without a deployment.

Every provider implements the same contract. Controllers, pages, caching, and editor preview work the same way for each of them, so you choose the vendor your editors already use.

Try it

What's included

  • Provider contract: CMSProviderService from @scayle/storefront/cms defines how a CMS integration fetches a page by slug, fetches the content of a category page, and detects editor sessions, the requests an editor makes while previewing a page inside the CMS. It also defines optional members for per-locale page paths and a preview redirect.
  • Provider integrations: Storyblok, Contentful, Contentstack, and Amplience each ship as an @scayle/storefront-cms-<provider> package. The package calls the vendor API and caches published content.
  • Local placeholder provider: The scayle provider is active until you set CMS_PROVIDER. It needs no credentials and renders a static welcome page.
  • CMS page routes: The homepage at / and /homepage, and content pages at /content/:slug. Both render the CmsPage page.
  • Category page content: Product listing pages fetch the CMS content of their category and render it as teaser content above the product grid and as SEO content on the first page.
  • Editor preview support: Each provider detects its editor session. A middleware lets the editor embed your shop in a frame, and a second middleware redirects preview requests for providers that open a placeholder path.
  • Draft content switch: STOREFRONT_CMS_ALLOW_DRAFTS decides whether an editor session sees unpublished content.
  • Content blocks: Editors assemble pages from layout, content, and product blocks. Each block maps to a Vue component in src/client/cms/providers/<provider>/components/. The block table shows which blocks each provider renders.
Demo shop homepage built from CMS content

Homepage with CMS content

What you can change

Configure

  • Which provider your shop uses, with CMS_PROVIDER. The Vite build reads it, so a change needs a rebuild.
  • Whether editor sessions see draft content, with STOREFRONT_CMS_ALLOW_DRAFTS. The server reads it when it creates the CMS service, so a change needs a restart.
  • The credentials of your provider, which are environment variables listed on the provider page.

Theme

  • The markup and styling of any block, by editing its Vue component in src/client/cms/providers/<provider>/components/.

Extend

  • Add a block type to the dispatcher of your provider, the Vue component that picks a component for each block type.
  • Read your own SEO fields by editing getPageMeta in your provider's service.ts.
  • Add a prop to a CMS page or change its template by overriding getViewProps or getTemplate on a controller in src/server/cms/controllers/cms-page.ts.
  • Change how many CMS images load eagerly by editing CMS_EAGER_LOADING_COUNT in src/client/cms/shared/useLcpPriority.ts. The server does not know the viewport, so the count is a fixed value. See Image priority.
  • Render a different 404 response for CMS pages by overriding renderNotFound on the controller.
  • Serve a CMS page at a new route by adding a subclass of CmsPageController that implements getSlug. CmsContentController is the model. CmsPageController is not exported, so export it from src/server/cms/controllers/cms-page.ts or add your subclass in that file. The route pattern, the mount, and the cacheableRoutes entry work as in Add your first page.
  • Change how a provider queries its CMS by subclassing its service in src/server/cms/providers/<provider>/service.ts and overriding its protected query methods, for example buildStoryQuery on Storyblok. Return your subclass from createCMSService.

Replace

  • Integrate a CMS the Storefront Application V3 has no provider for. You write a server provider that implements CMSProviderService, a client provider with the page components, and a types module, and you add its name to the CMS_PROVIDER list in vite.config.ts. See How it works for the files the application imports from each provider.

Constraints and limits

Permanent

  • Your build includes one provider. CMS_PROVIDER accepts scayle, storyblok, contentful, contentstack, or amplience, and any other value, including an empty string, fails the build with Invalid build environment. Each provider package pulls its own vendor SDK, so the build includes only the one you select. The directories of the other providers stay in the project and are not part of the build.
  • A missing slug, an empty result from the provider, and a CMSContentNotFoundError all end in your application's not-found page. There is no "coming soon" state for CMS content.
  • /content/:slug takes one path segment. A request with a / inside the slug, or with . or .. as the slug, gets the not-found page. The provider is asked for the slug content/<slug>.
  • getAlternatePaths and getPreviewRedirectPath are the optional members of the contract. fetchListingPageData is required, and a provider whose CMS holds no category content returns undefined from it. A listing page then renders without CMS content.
  • Each provider detects an editor session from a query parameter its editor adds to the preview URL. The Configuration section lists them.

Known limitations

  • The placeholder provider renders the same welcome page for every slug and marks it robots: noindex, nofollow. Category pages get no CMS content from it. Use it for component development, not in production. It also stays active when CMS_PROVIDER is set only in the runtime environment, because the build reads the variable. Every page then shows the welcome page.
  • The provider package caches published content, so a change in the CMS can take up to 5 minutes to show up, see Data cache TTLs. To remove one entry earlier, call cache.delete with its key, cms:<provider>:page:<slug>:<locale> for a page or cms:<provider>:plp:<categoryId>:<locale> for a category page. Amplience uses cms:amplience:page:<deliveryKey> and cms:amplience:plp:<deliveryKey>. /, /homepage, and /content/:slug are also listed in cacheableRoutes in storefront.config.ts with 600 seconds, so a CDN that honors the s-maxage header of these responses can serve a page for up to ten more minutes.
  • A CMS failure that is not a not-found result, such as a network error or a rate limit, is rethrown on / and /content/:slug and reaches the error handler registered in src/server/index.ts. Category pages catch it, log it, and render without CMS content.
  • Any request that carries the editor query parameter of the provider counts as an editor session. On Amplience the vse value must also be an Amplience staging domain. Otherwise the server ignores the parameter, logs a warning, and treats the request as a normal one. Nothing checks who sent the request. With drafts enabled, anyone who adds the parameter to a URL receives draft content, so leave STOREFRONT_CMS_ALLOW_DRAFTS unset on production.
  • With drafts disabled, an editor session still shows published content, but its response carries the provider's framing policy, so the page can be embedded in the editor's origin. The response cache gives every request with a non-empty editor parameter no-store headers, so a CDN never keeps an editor's preview. See Configure cacheable routes.
  • Rich text blocks of every provider pass their HTML through sanitizeCmsHtml in src/client/cms/shared/richtext.ts, which uses the DOMPurify defaults. The defaults remove target from links, so a link an editor sets to open in a new tab opens in the same tab. They also remove iframes. To keep target, add ADD_ATTR: ['target'] to the DOMPurify.sanitize call.
  • The Storyblok package maps the slug homepage to / when it builds alternate paths and keeps its own copy of that value. If you change HOMEPAGE_SLUG in src/server/cms/constants.ts, the homepage alternates point at the new slug instead of /.

How it works

A request for a CMS page runs through an SDK controller class that your application extends. The application also owns the provider factory, which creates the provider service for each request.

CmsHomepageController and CmsContentController extend CmsPageController, which extends BaseCMSPageController. Its fetchPageData call goes to the provider package that createCMSService creates, which fetches from your CMS.

The diagram shows the vendor providers. The placeholder provider is a class in your application and calls no CMS.

BaseCMSPageController comes from @scayle/storefront/controllers. Its view() method asks getSlug() for the slug, calls services.cms.fetchPageData(slug, request), and renders the result. services.cms is the cms slot, a named entry that src/server/registries.ts registers and the server resolves per request. The provider reads the locale from the storefront context it was created with, so the call carries no locale. view() renders the not-found page through renderNotFound() when getSlug() returns nothing, when the provider returns nothing, and when it throws CMSContentNotFoundError. It rethrows every other error.

Your application subclasses the base controller in src/server/cms/controllers/cms-page.ts. An abstract CmsPageController there builds the shared page props, and the two route controllers extend it. CmsHomepageController requests the slug homepage from the HOMEPAGE_SLUG constant and serves both / and /homepage. CmsContentController requests content/<slug> for /content/:slug. Both build the same page props. pageData and slug come from the fetch. meta comes from getPageMeta in your provider's service.ts. hreflangs, the tags that tell search engines which URL serves each country and language, use the per-locale paths from getAlternatePaths when the provider implements it and the page's own path otherwise. The homepage adds OnlineStore structured data.

Category pages use the same contract. ProductListingController calls fetchListingPageData(category.id, request) and passes the result to the listing page, which renders it as teaser and SEO content. A failed or empty fetch costs the CMS content and not the page.

In an editor session, the provider's isEditorMode(request) reads the editor query parameter. The CSP middleware in src/server/cms/middleware/csp.ts then merges the provider's cspConfig into every Content-Security-Policy header on the response, so the editor can frame your shop. The provider pages list the origins each one adds, and CMS preview requests on the Security Headers page explains the merge rules and how they affect each header.

The preview redirect middleware in src/server/cms/middleware/preview-redirect.ts calls the optional getPreviewRedirectPath, which only the Amplience provider implements. It opens a category page preview on a placeholder path and passes the edited item as a query parameter.

The cmsEditorData shared prop is a once prop, so the client keeps it after the first load instead of asking for it on every visit. It holds editor data only in an editor session, and on Amplience only when STOREFRONT_CMS_ALLOW_DRAFTS is true. The client-side editor code reads it to start the live preview.

If you replace the provider, these are the files the application imports from the active provider. On the server, @cms-server/service must export createCMSService, parseCmsEnv, and getPageMeta. On the client, @cms-client/plugin must export createCmsPlugin, and @cms-client/components/PageComponent.vue and @cms-client/components/ProductListingPageComponent.vue must exist. @cms-shared must export the CMSPageData type. All three aliases are set in vite.config.ts from CMS_PROVIDER.

Content blocks

Each provider renders its blocks through a dispatcher component in src/client/cms/providers/<provider>/components/. The table lists the blocks each dispatcher renders. The root page types, such as PageComponent, are not blocks.

BlockWhat it rendersStoryblokContentfulContentstackAmplience
TextComponentA heading or a paragraphYesYesYesYes
RichTextComponentFormatted proseYesYesYesYes
ImageComponentA responsive imageYesYesYesYes
VideoComponentA videoYesYesYesYes
LinkComponentA link around nested blocksYesYesYesYes
ButtonComponentA link styled as a buttonYesYesYesYes
AccordionComponentA group of accordion itemsYesYesYesYes
AccordionItemComponentOne accordion paneYesYesYesInside the accordion block
CountdownTimerComponentA countdown to an end dateYesYesYesYes
SectionComponentA container with a backgroundYesYesYesYes
GridComponentA grid of nested blocksYesYesYesYes
DividerComponentVertical spacing with an optional lineYesYesYesYes
SliderComponentA carousel of nested blocksYesYesYesYes
ProductSliderComponentA slider of products an editor picksYesYesNoYes
SmartSortingProductsSliderComponentA slider of products ranked by a smart sorting keyYesYesYesYes
RecentlyViewedProductsComponentA slider of the products the user viewed beforeYesYesYesYes
SingleProductComponentA spotlight card for one productYesYesYesYes

The names are the component names of the Vue files. The CMS identifies a block by its own name for it. That is the component name in Storyblok, the content type ID in Contentful, the content type UID in Contentstack, such as richtext-component, and the componentType value in Amplience, such as richText. The Storyblok page describes what each block renders in more detail.

Image priority

A CMS image is often the largest contentful paint (LCP) element of a page, the biggest piece of content the browser paints. The Storefront Application V3 sets fetchpriority and loading on the images of image blocks and section backgrounds so the browser fetches the likely LCP image first.

The page component of each vendor provider calls provideLcpPriority() from src/client/cms/shared/useLcpPriority.ts once per page. Every image block and every section with a background image then takes the next position in document order while it renders, including those inside nested sections, grids, and sliders. A section without a background image takes no position. Vue renders in the same order on the server and in the browser, so the positions match and hydration does not mismatch.

  • The image at position 0 gets fetchpriority="high". Every other image gets auto.
  • The images at positions 0 to 2 get loading="eager". The count is CMS_EAGER_LOADING_COUNT in the same file, and it is separate from the eager counts of the product image components. Every later image gets lazy.

On a category page, only the teaser content provides the counter. The SEO content below the product grid provides none, so its images load lazily with auto priority unless an editor marked them.

An editor forces high priority and eager loading on top of the automatic choice, per image, where the provider has a field for it:

  • Contentful: the isPriorityImage field, labeled "Priority image (LCP)", on the image and section content types. The section field applies to its background image.
  • Contentstack: the is_priority_image field, labeled "Priority image (LCP)", on the image and section content types.
  • Storyblok: the isPriorityImage field on the image and section blocks.
  • Amplience: no field exists, so the automatic choice always applies. To change it, pass fetchPriority or loading overrides to resolveImagePriority in ImageComponent.vue or SectionComponent.vue of the Amplience provider.

When the field is on, the image gets fetchpriority="high" and loading="eager" whatever its position. The first image keeps its own high priority, so two images can both be high. The bundled content models advise editors to turn it on for one image per page, and several high-priority images compete for bandwidth.

Setup

Connect your shop to a CMS provider. You need a space or project in the CMS with a content model that matches the blocks you want to use, and your provider's credentials.

  1. Set CMS_PROVIDER to storyblok, contentful, contentstack, or amplience in every environment that builds your shop.
  2. Set the credentials of your provider in the environment that runs the server. The provider page lists the variable names.
  3. Run pnpm cms:sync with CMS_PROVIDER set. It pulls your content model and regenerates the types in src/shared/types/cms/<provider>/. Run it again whenever the content model changes. The provider page lists the extra variables the script needs.
  4. Create the entries your pages request, using the slugs in the table below. The provider page explains how a slug maps to an entry in that CMS.
  5. Build and start the shop, then open /.
PageSlug the application requests
Homepage at / and /homepagehomepage
Content page at /content/:slugcontent/<slug>
Category pagec/c-<categoryId>

You see the content of your homepage entry instead of the welcome page of the placeholder provider. When you use a real provider, the server checks its credentials at startup and stops with an error if one is missing.

The Storefront CLI can do steps 1 and 2 for you. pnpx @scayle/storefront-cli setup cms <provider> writes CMS_PROVIDER and the credentials into .env and can import the bundled content model into a new space. It never writes STOREFRONT_CMS_ALLOW_DRAFTS, so set that yourself where editors preview, and restart the server afterward. The setup cms flags list the flags and the variables each provider writes.

Configuration

VariableWhen it is readDefaultEffect
CMS_PROVIDERBuild timescayleSelects the provider directory behind the three CMS aliases.
STOREFRONT_CMS_ALLOW_DRAFTSWhen the server creates the CMS serviceDrafts off unless the value is true in any letter caseLets an editor session fetch draft content.

An editor session sees draft content only when both conditions hold: the request carries the provider's editor query parameter, and STOREFRONT_CMS_ALLOW_DRAFTS is true. Without the variable, an editor session reads the same cached published content as every other request. Enable it only in the environment that serves editor previews. Each provider page lists the variables it needs, including the preview token for the providers that have one.

ProviderEditor query parameter
Storyblok_storyblok
Contentful_editorMode
Contentstacklive_preview
Ampliencevse (or _vse), which must be an Amplience staging domain

The three aliases @cms-server, @cms-client, and @cms-shared are described in Project Structure. Files that work with every provider import the page payload type through @cms-shared. Files that belong to one provider import @shared/types/cms/<provider> directly.

Customization guides

Add a block type

Add a block that editors can place on pages. Every provider follows the same four steps and differs in how its dispatcher recognizes a block.

  1. Create the block in your CMS and allow it inside the blocks where editors may use it.
  2. Run pnpm cms:sync to regenerate the types.
  3. Create the Vue component in src/client/cms/providers/<provider>/components/. DividerComponent.vue is a small model. It takes the block as a contentElement prop typed with the generated type.
  4. Import the component in your provider's dispatcher and add an entry for your block type to its BLOCKS map. Set suspense: true when the component awaits in setup or is wrapped in defineAsyncComponent, and false otherwise. Contentful uses a BLOCKS list of toBlockEntry({ guard, component, suspense }) entries instead of a map.

You see the block render when you open a page that uses it in the editor preview. A block type without an entry shows a "not implemented" notice in development and renders nothing in a production build. On Storyblok and Amplience, BLOCKS has a key for every generated block type, so pnpm typecheck also fails until the entry exists. Contentful checks only that the component accepts the type its guard narrows to. Contentstack keys are plain strings, so nothing checks them.

The provider pages show the dispatcher code: Storyblok keys the map by the component name, Contentful pairs a generated type guard with the component, and Contentstack keys it by the content type UID. The Amplience map is keyed by the componentType value in AmplienceBlockDispatch.vue.

Read your own SEO fields

Point the page metadata at the fields of your own content model. The CMS page controller calls getPageMeta and builds the title, description, robots directive, and share image from the result.

  1. Open src/server/cms/providers/<provider>/service.ts.
  2. Change the field names in getPageMeta.

getPageMeta takes the page payload of the provider and returns a CMSPageMeta with optional title, description, robots, and image values. It returns undefined for a page type it does not map. Storyblok shows a full example.

The title, description, and robots directive from getPageMeta apply to CMS pages. A CMS page with a title from getPageMeta uses it. A CMS page without one falls back to the shop name. A category page that shows CMS content takes only the share image from getPageMeta, and only where the provider returns one for a listing. Of the bundled providers, only Storyblok does. Its title, description, and robots directive come from the listing page's own translations and indexability rule.

Add a prop to a CMS page

Send an extra value from the server to the CmsPage page. The homepage controller already does this for its OnlineStore structured data.

  1. Override getViewProps on the controller. Spread super.getViewProps(data) first so the page keeps its base props.
  2. Declare the prop in defineProps in src/client/pages/CmsPage.vue.

Override it on CmsPageController in the same file to reach every CMS page, or on one subclass to reach one route. Inertia.serverOnly sends the prop with the server-rendered page and leaves it out after a client-side navigation.

Best practices

Import the page payload through the CMS aliases

Code outside a provider directory imports the page payload type from @cms-shared and reads provider functions from @cms-server/service. Importing @shared/types/cms/storyblok from a page or controller ties it to one vendor. The per-provider typecheck verifies this boundary.

Commit the generated types and the content model files

Run pnpm cms:sync after every content model change and commit the result: src/shared/types/cms/<provider>/ and .scayle/cms/contentModel/<provider>/. CI and deployments then build without the credentials the sync needs, and a review shows what a content model change did to the types. The Storefront CLI import reads the committed content model folder.

Run the full typecheck after changing CMS code

pnpm typecheck runs vue-tsc once with the aliases pointing at the placeholder provider and then once per real provider through typecheck:cms-providers. A plain vue-tsc --noEmit does not check the types of your provider.

Return undefined from getPageMeta for content you do not recognize

The getPageMeta of every provider returns undefined for a page type it does not map. A CMS page then uses the shop name as its title and sends no robots directive and no share image. A category page keeps its own title, description, and robots directive and shows no share image. Guessing fields for an unknown page type sends wrong metadata to search engines.

Troubleshooting

Issue: The server stops at startup with Invalid <Provider> CMS environment.

Possible causes: A credential of the selected provider is not set or is empty. The message lists each invalid variable by name and never prints its value.

Solution:

  1. Set every variable the message lists.
  2. Start the server again.

Prevention: Compare the environment with the provider page before you deploy.

Reference

Provider pages