frontic-experience element. You build it once. Every experience your team publishes afterwards goes through it, with no further deploy.
This page is for storefronts that already render Shopware’s Shopping Experiences from the Store API - with Shopware Frontends, or with a CMS renderer of your own in Nuxt or Next.js. If you’d rather hand the work to a coding agent, start with the agent prompt; the rest of the page explains what it builds.
Creating and publishing an experience works the same as for the default storefront - see Frontic Experiences in Shopware. Only the rendering on your storefront is yours to add.
Agent prompt
Paste this into the coding agent you use on your storefront’s repository. It carries the whole contract, so the agent doesn’t need this page open.Have your coding agent add the Frontic Experience element to a headless Shopware storefront
Before you start
- Frontic plugin 1.1.1 or newer. Older versions return the element without its markup over the Store API.
- A real domain on the sales channel. An experience that shows the page’s own category or product - see Experiences on category and product pages - is rendered per request, for the sales channel’s domain in the request’s language. The sales channel your storefront’s access key belongs to needs a domain with an
httporhttpsURL for each language you serve. A placeholder such asdefault.headless0doesn’t count.
What the Store API returns
The plugin registers one block and one element, both of typefrontic-experience. The block has a single slot named content, which holds the element. In a CMS page response the element carries the finished markup in data:
Shopware resolves everything else on its side: the language of the request, and for a per-request experience the render itself. Your storefront never talks to Frontic for this.
The markup to render
Whatever the framework, the component produces this:- The shadow root. An experience brings its own styles and expects to be isolated from yours. Mounted into the light DOM, its CSS leaks into your page and your CSS leaks into it.
- The class names and
data-frontic-slot-id. They match the default storefront, and the Designer uses them to find the slot when it previews an experience on your storefront.data-frontic-recordiskind:keyfromdata.record, and is left out when there is no record. - Scripts have to run. An interactive experience carries its scripts inline. A browser runs them when it parses a server-rendered page. After a client-side navigation the markup arrives through
innerHTML, which leaves both the<template>and the scripts inert, so the component attaches the shadow root itself and re-creates each script.
Build the element
1
Add the shared helper
One framework-free file holds the element’s type and the browser-side mount.On a server-rendered page the browser has already turned the template into a shadow root and run its scripts, so
frontic-experience.ts
mountExperience finds no template and does nothing.2
Add the component
- Vue (Nuxt)
- React (Next.js)
Keep the helper in
utils/, so Nuxt imports it for you.components/cms/CmsElementFronticExperience.vue
3
Register it with your CMS renderer
The last step tells your storefront that
frontic-experience maps to the new component.- Shopware Frontends
- Nuxt
- Next.js
Shopware Frontends resolves CMS components by name, block and element separately. The element component above already has the right name,
CmsElementFronticExperience. Add the block next to it, and register both globally, like every custom CMS element.components/cms/CmsBlockFronticExperience.vue
nuxt.config.ts
4
Check it
Publish an experience into a layout, then open the page on your storefront twice: once by loading its URL directly, and once by navigating to it from another page. Both have to show the experience, with working interactions. If only the direct load works, the client-side mount is missing.
Good to know
- Load category and product pages through their own routes. A per-request experience needs to know which category or product the page shows. Shopware only knows that on the Store API’s category and product routes. Loaded as a bare CMS page by its ID, the element comes back with empty markup.
- Add to Cart doesn’t reach a headless cart yet. Add to Cart buttons inside an experience talk to the default storefront’s cart. On a headless storefront they have no cart to add to. Until that changes, leave cart actions out of experiences for a headless storefront, and link to the product page instead.
- Links are plain links. Product and category links inside an experience are root-relative Shopware SEO paths. They work as full page loads. To route them through your framework, listen for clicks on the host element - a click that starts inside a shadow root only shows its link in
event.composedPath(). - The markup is trusted. It comes from your own Shopware instance, and it’s mounted as is, scripts included - the same trust Shopware’s HTML element asks for.
- One language per response. Shopware returns the markup for the language of the Store API request. A language the experience wasn’t built in gets its primary language.
Related
Shopware connector
Installing the plugin, and creating an experience from a
Shopping Experience layout.
Publishing
Versions, going live, and rolling back an experience.
Building an experience
The canvas, stages, and Designer settings.
Experience Designer
What experiences are and how to create one.