shopware/frontends - cms-base

Nuxt layer that provides an implementation of all CMS components in Shopware based on utility-classes using atomic css syntax (UnoCss / Tailwind).

It is useful for projects that want to use the CMS components but design their own layout.

Features

• Vue components for Shopping Experiences CMS
• CMS sections, blocks and elements styled using Tailwind CSS classes
• 🚀 Empowered by @shopware/composables

Setup

Install npm package:

# ✨ Auto-detect
npx nypm install -D @shopware/cms-base-layer

# npm
npm install -D @shopware/cms-base-layer

# yarn
yarn add -D @shopware/cms-base-layer

# pnpm
pnpm install -D @shopware/cms-base-layer

# bun
bun install -D @shopware/cms-base-layer

# deno
deno install --dev @shopware/cms-base-layer

Then, register the Nuxt layer in nuxt.config.ts file:

// https://v3.nuxtjs.org/api/configuration/nuxt.config
export default defineNuxtConfig({
  extends: ["@shopware/composables/nuxt-layer", "@shopware/cms-base-layer"],
  shopware: {
    endpoint: "https://demo-frontends.shopware.store/store-api/",
    accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  },
  modules: ["@shopware/nuxt-module"],
  /**
   * Commented because of the StackBlitz error
   * Issue: https://github.com/shopware/frontends/issues/88
   */
  typescript: {
    // typeCheck: true,
    strict: true,
  },
  telemetry: false,
});

Basic usage

Since all CMS components are registered in your Nuxt application, you can now start using them in your template (no imports needed):

/* Vue component */

// response object can be a Product|Category|Landing Page response from Shopware 6 store-api containing a layout (cmsPage object) built using  Shopping Experiences
<template>
    <CmsPage v-if="response.cmsPage" :content="response.cmsPage"/>
</template>

You can use default styling by installing/importing Tailwind CSS stylesheet in your project.

See a short guide how to use cms-base package in your project based on Nuxt v3.

Default styling

The components are styled using Tailwind CSS utility classes, so you can use them in your project without any additional configuration if your project uses Tailwind CSS.

This layer provides a default Tailwind CSS configuration (see uno.config.ts for details), which is used to style the components. If you want to customize the styling, you can do so by creating your own Tailwind CSS configuration file and extending the default one:

// nuxt.config.ts
export default defineNuxtConfig({
  // ...
  unocss: {
    nuxtLayers: true, // enable Nuxt layers for UnoCSS
  },
})

// uno.config.ts
import config from './.nuxt/uno.config.mjs'

export default config

Thanks to this, you can use the default configuration provided by this layer, or extend/overwrite it with your own customizations in your end-project:

// uno.config.ts
import { mergeConfigs } from '@unocss/core'
import config from './.nuxt/uno.config.mjs'

export default mergeConfigs([config, {
  theme: {
    colors: {
      primary: '#ff3e00',
      secondary: '#1c1c1c',
    },
  },
}])

See the UnoCSS reference for more information on how to configure UnoCSS in Nuxt when work with layers.

🖼️ Image Optimization

This layer includes Nuxt Image configuration optimized for Shopware 6 instances, with a custom provider that maps Nuxt Image modifiers to Shopware's query parameters (width, height, quality, format, fit).

Note for Cloud (SaaS) Users: Image optimization and all modifiers used in the Nuxt Image module are handled automatically by Shopware Cloud infrastructure powered by Fastly CDN. No additional configuration or plugins are required - simply use <NuxtImg> and all transformations (format conversion, quality adjustment, responsive sizing) work out of the box through Fastly's Image Optimizer.

Features

• ✅ Automatic WebP/AVIF format conversion
• ✅ Responsive image sizing based on viewport
• ✅ Lazy loading support
• ✅ Quality optimization
• ✅ Multiple image presets for common use cases
• ✅ Works with Shopware Cloud (SaaS) and self-hosted instances

Configuration

The layer comes pre-configured with optimized settings. No additional setup is required! The configuration includes:

Available Presets:

• productCard - Product listing images (WebP, quality 90, cover fit)
• productDetail - Product detail page images (WebP, quality 90, contain fit)
• thumbnail - Small thumbnails (150x150, WebP, quality 90)
• hero - Hero banners (WebP, quality 95, cover fit)

Responsive Breakpoints:

• xs: 320px, sm: 640px, md: 768px, lg: 1024px, xl: 1280px, xxl: 1536px

Usage in Components

Replace standard <img> tags with <NuxtImg> to enable automatic optimization:

<!-- Using presets -->
<NuxtImg
  src="https://cdn.shopware.store/media/path/to/image.jpg"
  preset="productCard"
  :width="400"
  alt="Product"
  loading="lazy"
/>

<!-- Custom modifiers -->
<NuxtImg
  src="https://cdn.shopware.store/media/path/to/image.jpg"
  :width="800"
  :height="600"
  format="webp"
  :quality="85"
  fit="cover"
  alt="Custom image"
/>

<!-- Using with dynamic Shopware media URLs -->
<NuxtImg
  :src="product.cover.media.url"
  preset="productDetail"
  :width="800"
  :alt="product.cover.media.alt"
/>

Supported Modifiers

Shopware supports the following URL parameters for image transformation:

| Modifier | Description | Example | Support | |----------|-------------|---------|---------| | width | Image width in pixels | 400 | ✅ Always supported | | height | Image height in pixels | 600 | ✅ Always supported | | quality | Image quality (0-100) | 85 | ⚠️ Cloud/Plugin required* | | format | Output format | webp, avif, jpg, png | ⚠️ Cloud/Plugin required* | | fit | Resize behavior | cover, contain, fill | ⚠️ Cloud/Plugin required* |

*Advanced transformations (quality, format, fit) are available in:

• Shopware Cloud (SaaS): Built-in support via managed infrastructure. For a complete list of supported image transformation parameters, see Fastly Image Optimizer Query Parameters.
• Self-hosted instances: Require thumbnail processor plugins like FroshPlatformThumbnailProcessor or third-party CDN integration

How It Works

This layer includes a custom Shopware provider for Nuxt Image that maps modifiers to Shopware's query parameters:

• width modifier → ?width=400
• height modifier → ?height=300
• quality modifier → ?quality=85
• format modifier → ?format=webp
• fit modifier → ?fit=cover

When you use <NuxtImg>, the custom provider automatically converts your component props into the correct URL format for Shopware. The images are then processed on-the-fly by Shopware Cloud (SaaS) infrastructure or your configured thumbnail processor.

🔍 Understanding Image Processing in Shopware

Built-in Thumbnail Generation: Shopware has native thumbnail generation (using GD2 or ImageMagick) that creates predefined sizes (400x400, 800x800, 1920x1920) during image upload. These thumbnails are generated once and stored on your server.

Dynamic On-the-Fly Transformations: For dynamic image transformations via query parameters (like ?width=800&format=webp), you need remote thumbnail generation configured:

• Shopware Cloud (SaaS): ✅ Fully supported out-of-the-box via Fastly CDN - all query parameters work automatically
• Self-hosted: ⚠️ Requires additional setup:
  • Install a plugin like FroshPlatformThumbnailProcessor for on-the-fly processing, OR
  • Configure external middleware (Thumbor, Sharp, imgproxy) via remote thumbnail generation

Without remote thumbnail generation configured, query parameters will be ignored and only the predefined static thumbnails will be served.

💡 Recommendation: If you're self-hosting Shopware and want to use dynamic image transformations with Nuxt Image modifiers, install the FroshPlatformThumbnailProcessor plugin first to enable on-the-fly processing.

Customizing Configuration

You can extend or override the default settings in your project's nuxt.config.ts:

export default defineNuxtConfig({
  extends: ["@shopware/cms-base-layer"],

  image: {
    // Change default quality
    quality: 85,

    // Add/change formats
    formats: ['avif', 'webp', 'jpg'],

    // Override or add presets
    presets: {
      // Override existing preset
      productCard: {
        modifiers: {
          format: 'avif',
          quality: 80,
          fit: 'cover',
        }
      },
      // Add custom preset
      categoryBanner: {
        modifiers: {
          format: 'webp',
          quality: 90,
          width: 1200,
          height: 400,
          fit: 'cover',
        }
      }
    }
  }
})

🖼️ Image Placeholder

This layer provides a useImagePlaceholder composable that generates an SVG placeholder for images during loading. The placeholder features a centered icon with a subtle background.

Customizing Placeholder Color

You can customize the placeholder color globally in your project's app.config.ts:

export default defineAppConfig({
  imagePlaceholder: {
    color: "#your-color-here", // Default: #543B95
  },
});

Or use a custom color for specific instances:

<script setup>
const customPlaceholder = useImagePlaceholder("#FF0000");
</script>

<template>
  <NuxtImg :placeholder="customPlaceholder" src="..." />
</template>

📘 Available components

The list of available blocks and elements is here.

🔄 Overwriting components

The procedure is:

• find a component in component's list, using a Vue devtools or browsing the github repository
• take its name
• create a file with the same name and place it into ~/components dir in your nuxt project (or wherever according your nuxt config)

✅ Thanks to this, nuxt will take the component registered in your app instead of the one registered by this nuxt layer.

Internal components

❗Internal components are not a part of public API. Once overwritten you need to track the changes on your own.

There is also a possibility to override the internal components, shared between public blocks and elements, the ones starting with Sw prefix, like SwSlider.vue or SwProductCard.vue.

An example: some components use SwSharedPrice.vue to show prices with corresponding currency for products in many places like product card, product details page and so on. In order to change the way how the price is displayed consistently - create a one component with a name SwSharedPrice.vue and that's it. The new component will be used everywhere where is "imported" (autoimported actually).

⚠️ <RouterLink/> components used

Some components use RouterLink component internally, available in Vue Router. In order to parse CMS components correctly and avoid missing component warning, it's highly recommended to have Vue Router installed or Nuxt router enabled in your application.

TypeScript support

All components are fully typed with TypeScript.

No additional packages needed to be installed.

Links

• 📘 Documentation

• 👥 Community (#composable-frontend)

Changelog

Full changelog for stable version is available here

Latest changes: 2.0.0

Major Changes

• #1944 c41a839 Thanks @mkucmus! - Updates the @shopware/cms-base-layer package with the following changes:

  • Adds support for the new SwQuantitySelect component
  • Updates the SwProductAddToCart component to use the new SwQuantitySelect component
  • Fixes the Status component to use the new state classes
  • Updates the uno.config.ts file to include default styling that can be used and extended in the end-project:

  Nuxt UnoCSS Configuration Example

  // nuxt.config.ts in your end-project
  {
    unocss: {
      nuxtLayers: true; // enable Nuxt layers support in order to merge UnoCSS configurations
    }
  }

  UnoCSS Configuration Example

  // uno.config.ts in your end-project
  import { mergeConfigs } from "@unocss/core";
  import baseConfig from "./.nuxt/uno.config.mjs";
  
  export default mergeConfigs(baseConfig, {
    // will be merged with the base config - all optional
    theme: {
      colors: {
        "brand-primary": "#ff3e00",
        "brand-secondary": "#ff6a00",
      },
    },
    safelist: ["states-success"],
    preflights: [
      {
        getCSS: () => `
          body {
              font-family: 'Inter', sans-serif;
              -moz-osx-font-smoothing: grayscale;
              -webkit-font-smoothing: antialiased;
          }
          `,
      },
    ],
  });

Minor Changes

• #2030 22ff62e Thanks @mkucmus! - Introduce new UI components, refine listing filters (structure and UX), add global collapse animations, and improve type safety.

  Features

  • New UI components:
    • SwFilterChips – shows active filters as removable chips
    • SwSortDropdown – sorting dropdown
    • SwProductListingPagination – listing pagination
    • Checkbox – reusable checkbox
    • ChevronIcon – configurable chevron (up/down/left/right)
    • RadioButton – reusable radio button
    • SwitchButton – toggle switch

  Refactors

  • SwFilterProperties:
    • Replace computed factory with isChecked() and selectValue() helpers for better performance and readability.
  • Filter collapse animation:
    • Unified expand/collapse animations for SwFilterProperties, SwFilterRating, SwFilterShippingFree, and SwFilterPrice using UnoCSS preflights.

  TypeScript fixes

  • SwProductListingFilters:
    • Provide fallbacks (?? [], ?? '') when passing getSortingOrders and getCurrentSortingOrder.
  • SwFilterChips:
    • Relax prop types to accept union types compatible with both full Shopware schemas and simplified helper types.

  Code quality improvements

  • SwFilterPrice:
    • Remove unnecessary optional chaining on props.selectedFilters to prevent masking undefined errors
  • Checkbox component:
    • Replace outline-blue-500 with outline-brand-primary for brand consistency
    • Make label prop optional to support checkbox-only pattern
  • SwFilterShippingFree:
    • Add i18n support using useCmsTranslations instead of hardcoded "free delivery" text
  • SwFilterProperties:
    • Remove unnecessary empty label prop from Checkbox usage

  Note: Transition classes are globally available via UnoCSS preflights.

• #2139 20d1066 Thanks @mkucmus! - Added a new SwProductReviewsForm component that allows logged-in customers to submit product reviews.

• #1959 c77daa6 Thanks @patzick! - Updated default types to Shopware 6.7

• #2176 c647baf Thanks @mkucmus! - - Extract product listing data early from CMS page responses to enable SSR rendering

  • Remove ClientOnly wrappers from SwProductListingFilters and SwFilterChips components
  • Resolve hydration mismatches on category pages with filters

Patch Changes

• #2174 e9f3d97 Thanks @mkucmus! - Added a new image placeholder.

• #2162 e1fae3e Thanks @mkucmus! - Replace hardcoded colors with theme tokens, add image placeholder composable, improve URL encoding for special characters in image paths, enhance CMS block layouts, and use useTemplateRef for better type safety

• #2128 efe125e Thanks @mkucmus! - Enhanced SwProductReviews component with reviewer names, shop feedback, and star ratings using direct SVG imports.

• #2008 3a1bca9 Thanks @mkucmus! - Added missing labels for SwQuantitySelect component.

• #1951 3f2379b Thanks @mkucmus! - Use proper paths for components configuration

• #2154 168989e Thanks @mkucmus! - Implicitly set public components as global to expose them for templates that extend from the base one.

• Updated dependencies [87771c3, 22ff62e, a44d871, e43d9b7, 2cbda25, 2cbda25, 7fe2ef9, 70dcf95, 56cd178, c647baf, e1fae3e, c647baf, c77daa6]:

  • @shopware/[email protected]
  • @shopware/[email protected]
  • @shopware/[email protected]