> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frontic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless Shopware storefronts

Shopware's default storefront renders the **Frontic Experience** element out of the box, because the Frontic plugin ships its template. A headless storefront renders Shopping Experiences with its own components, so it needs one more: a component for the `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](#agent-prompt); the rest of the page explains what it builds.

> [!NOTE]
>
> Creating and publishing an experience works the same as for the default storefront - see [Frontic Experiences in Shopware](https://docs.frontic.com/connectors/shopware.md#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

Add support for the Frontic Experience CMS element to this storefront. The storefront already renders Shopware Shopping Experiences from the Store API. First find how it maps Shopware CMS block and element types to components, and follow that pattern and the repo's conventions.

The block type is frontic-experience. It has one slot named content, which holds an element of type frontic-experience. Register a component for the block that renders that slot, and a component for the element.

The element carries everything in its data field. data.markup is the finished markup as one string, a style tag followed by HTML; an empty string or a missing data field means there is nothing to show, and the component then renders the empty container only. data.record is null, or an object with kind (product or category) and key. Do not fetch anything for this element, and do not read its config.

Render this structure: an outer div with class cms-element-frontic-experience, the attribute data-frontic-slot-id set to the element's id, and, when data.record is present, data-frontic-record set to kind:key. Inside it, a div with class frontic-experience-host. Inside that, a template element with shadowrootmode="open" that contains data.markup unescaped, so server-rendered pages get a declarative shadow root. Do not render the markup in the light DOM.

The rendered element looks like this, here on a category page:

```html theme={"theme":"css-variables"}
<div class="cms-element-frontic-experience"
     data-frontic-slot-id="0193a5c8e2f47a31b6d4c2e8f1a09b57"
     data-frontic-record="category:0193a5c9f1b27c44a8e3d5f6b7c81d92">
  <div class="frontic-experience-host">
    <template shadowrootmode="open">
      <!-- data.markup -->
    </template>
  </div>
</div>
```

After a client-side navigation the browser does not parse the template, so it stays in the host as an inert child. On mount, and whenever the markup changes, check the host for such a template child. If there is one, attach an open shadow root to the host or reuse the one it has, replace the shadow root's children with the template's content, remove the template, and replace every script element inside the shadow root with a newly created script that has the same attributes and text, so the scripts run. If there is no template child, the browser already parsed it: leave the host alone. Make sure hydration does not warn about or overwrite the host's content.

Do not sanitize or rewrite the markup. Do not add a dependency for this.

When you're done, verify both paths in a browser: a direct load of a page with a published experience, and a client-side navigation to it. In both, the experience has to be visible inside a shadow root and its interactive parts have to respond. Tell me what you verified and what you couldn't.

## 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](https://docs.frontic.com/connectors/shopware.md#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 `http` or `https` URL for each language you serve. A placeholder such as `default.headless0` doesn't count.

## What the Store API returns

The plugin registers one block and one element, both of type `frontic-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`:

```json theme={"theme":"css-variables"}
{
  "id": "0193a5c8e2f47a31b6d4c2e8f1a09b57",
  "type": "frontic-experience",
  "data": {
    "markup": "<style>…</style><div>…</div>",
    "record": { "kind": "category", "key": "0193a5c9f1b27c44a8e3d5f6b7c81d92" }
  }
}
```

| Field | What it holds |
| - | - |
| `data.markup` | The experience, ready to mount: a `<style>` element followed by HTML. An empty string means there is nothing to show - the experience isn't published, or its render wasn't available for this request. |
| `data.record` | The category or product the page shows, on pages loaded through the Store API's category and product routes. `null` everywhere else. |

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:

```html theme={"theme":"css-variables"}
<div class="cms-element-frontic-experience"
     data-frontic-slot-id="0193a5c8e2f47a31b6d4c2e8f1a09b57"
     data-frontic-record="category:0193a5c9f1b27c44a8e3d5f6b7c81d92">
  <div class="frontic-experience-host">
    <template shadowrootmode="open">
      <!-- data.markup -->
    </template>
  </div>
</div>
```

Three things matter here:

* **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-record` is `kind:key` from `data.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.

```ts frontic-experience.ts theme={"theme":"css-variables"}
export type FronticSlot = {
  id: string;
  data?: {
    markup: string;
    record?: { kind: "product" | "category"; key: string } | null;
  } | null;
};

export function shadowTemplate(markup: string): string {
  return `<template shadowrootmode="open">${markup}</template>`;
}

/** Mounts a template the browser did not parse, which is every one after a client-side navigation. */
export function mountExperience(host: HTMLElement): void {
  const template = host.querySelector<HTMLTemplateElement>(":scope > template");
  if (!template) return;
  const root = host.shadowRoot ?? host.attachShadow({ mode: "open" });
  root.replaceChildren(template.content);
  template.remove();
  for (const inert of root.querySelectorAll("script")) {
    const script = document.createElement("script");
    for (const { name, value } of inert.attributes) script.setAttribute(name, value);
    script.textContent = inert.textContent;
    inert.replaceWith(script);
  }
}
```

On a server-rendered page the browser has already turned the template into a shadow root and run its scripts, so `mountExperience` finds no template and does nothing.

**2. Add the component**

> [tab] Vue (Nuxt)
>
> Keep the helper in `utils/`, so Nuxt imports it for you.
>
> ```vue components/cms/CmsElementFronticExperience.vue theme={"theme":"css-variables"}
> <script setup lang="ts">
> const props = defineProps<{ content: FronticSlot }>();
>
> const markup = computed(() => props.content.data?.markup ?? "");
> const record = computed(() => props.content.data?.record);
>
> const host = ref<HTMLElement>();
> const mount = () => host.value && mountExperience(host.value);
> onMounted(mount);
> watch(markup, mount, { flush: "post" });
> </script>
>
> <template>
>   <div
>     class="cms-element-frontic-experience"
>     :data-frontic-slot-id="content.id"
>     :data-frontic-record="record ? `${record.kind}:${record.key}` : undefined"
>   >
>     <div v-if="markup" ref="host" class="frontic-experience-host" v-html="shadowTemplate(markup)" />
>   </div>
> </template>
> ```

> [tab] React (Next.js)
>
> The element itself renders on the server. A small client component mounts the template after client-side navigations.
>
> ```tsx components/FronticExperience.tsx theme={"theme":"css-variables"}
> import { shadowTemplate, type FronticSlot } from "@/lib/frontic-experience";
> import { FronticExperienceMount } from "./FronticExperienceMount";
>
> export function FronticExperience({ element }: { element: FronticSlot }) {
>   const markup = element.data?.markup ?? "";
>   const record = element.data?.record;
>
>   return (
>     <div
>       className="cms-element-frontic-experience"
>       data-frontic-slot-id={element.id}
>       data-frontic-record={record ? `${record.kind}:${record.key}` : undefined}
>     >
>       {markup && (
>         <>
>           <div
>             className="frontic-experience-host"
>             suppressHydrationWarning
>             dangerouslySetInnerHTML={{ __html: shadowTemplate(markup) }}
>           />
>           <FronticExperienceMount key={`${element.id}:${record?.key ?? ""}`} slotId={element.id} />
>         </>
>       )}
>     </div>
>   );
> }
> ```
>
> ```tsx components/FronticExperienceMount.tsx theme={"theme":"css-variables"}
> "use client";
>
> import { useEffect } from "react";
> import { mountExperience } from "@/lib/frontic-experience";
>
> export function FronticExperienceMount({ slotId }: { slotId: string }) {
>   useEffect(() => {
>     const host = document.querySelector<HTMLElement>(
>       `[data-frontic-slot-id="${slotId}"] > .frontic-experience-host`,
>     );
>     if (host) mountExperience(host);
>   }, [slotId]);
>
>   return null;
> }
> ```

**3. Register it with your CMS renderer**

The last step tells your storefront that `frontic-experience` maps to the new component.

> [tab] Shopware Frontends
>
> 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](https://developer.shopware.com/frontends/guides/cms/custom-elements.html).
>
> ```vue components/cms/CmsBlockFronticExperience.vue theme={"theme":"css-variables"}
> <script setup lang="ts">
> import type { Schemas } from "#shopware";
>
> const props = defineProps<{ content: Schemas["CmsBlock"] }>();
> const { getSlotContent } = useCmsBlock(props.content);
> </script>
>
> <template>
>   <CmsGenericElement :content="getSlotContent('content')" />
> </template>
> ```
>
> ```ts nuxt.config.ts theme={"theme":"css-variables"}
> export default defineNuxtConfig({
>   components: [{ path: "~/components/cms", pathPrefix: false, global: true }, "~/components"],
> });
> ```

> [tab] Nuxt
>
> With a CMS renderer of your own, add the type wherever you map Shopware element types to components.
>
> ```vue theme={"theme":"css-variables"}
> <CmsElementFronticExperience v-if="slot.type === 'frontic-experience'" :content="slot" />
> ```
>
> If your renderer maps block types too, map the `frontic-experience` block to a component that renders its `content` slot and nothing else.

> [tab] Next.js
>
> Add the type to the switch or map that turns Shopware element types into components.
>
> ```tsx theme={"theme":"css-variables"}
> if (slot.type === "frontic-experience") {
>   return <FronticExperience element={slot} />;
> }
> ```
>
> If your renderer maps block types too, map the `frontic-experience` block to a component that renders its `content` slot and nothing else.

**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

> [card] [Shopware connector](https://docs.frontic.com/connectors/shopware.md)
>
> Installing the plugin, and creating an experience from a
> Shopping Experience layout.

> [card] [Publishing](https://docs.frontic.com/designer/publishing.md)
>
> Versions, going live, and rolling back an experience.

> [card] [Building an experience](https://docs.frontic.com/designer/building.md)
>
> The canvas, stages, and Designer settings.

> [card] [Experience Designer](https://docs.frontic.com/designer/overview.md)
>
> What experiences are and how to create one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.