Nuxt Layers & Templates in Composable Frontends

[Maciek Kucmus (mkucmus)]

📢 We're introducing an updated storefront scaffolding model based on Nuxt Layers and the official Composable Frontends templates.
This is an architectural direction update. We want feedback early.

TL;DR — We Need Your Feedback

Before diving into the details, here's what we're looking for:

1. Does the base vs extended split make sense for your workflow?
2. Are CMS override patterns intuitive — or do you expect something different?
3. Is the semantic token structure (brand-*, surface-*, states-*) sufficient for real-world theming?
4. What would block adoption in an existing project?
5. What documentation would you need to get started?

If you build or maintain multiple storefronts, your feedback is especially valuable.

👉🏼 Full details below, however you are able to see the templates in action by running StackBlitz example in just one click:

⚠️ StackBlitz notice: This demo runs in a WebContainer (browser-based Node.js). You may see warnings or errors in the console that don't occur in a regular local or CI environment — these are typically related to WebContainer filesystem limitations and can be safely ignored.

The Layer Chain

Every storefront built with Frontends follows a layered architecture. The full chain looks like this:

Your Project (or vue-starter-template-extended)
  └─ extends → vue-starter-template
                  └─ extends → @shopware/composables/nuxt-layer
                               @shopware/cms-base-layer

Each layer adds structure, components, and configuration. Child layers inherit everything from their parents and can selectively override what they need.

Templates

Shopware Frontends provides official templates as starting points:

Template	Purpose	Extends
vue-starter-template	Structured base with pages, layout, CMS, SSR, i18n	cms-base-layer, composables
vue-starter-template-extended (Lumora)	Reference child layer — proves the override model works	vue-starter-template

Choose your entry point based on how much structure you want to start with.

Base: vue-starter-template

The base template is a fully functional storefront. It provides:

• Pages — PDP, PLP, checkout (cart → order → success), account (profile, addresses, orders, password/email change), search, wishlist, newsletter, registration confirmation
• Layout — header, footer, navigation, side menu, account dropdown, modals
• CMS — full Shopping Experiences rendering via @shopware/cms-base-layer
• i18n — multi-language support (en-GB, de-DE, pl-PL) with @nuxtjs/i18n
• SSR + ISR — server-side rendering with 60-minute ISR caching; checkout and account pages run client-side only
• Image optimization — Shopware CDN image provider with presets via @nuxt/image
• Design tokens — UnoCSS with semantic color system (brand, surface, states, overlays)
• Accessibility — integrated via @nuxt/a11y

It focuses on structure and integration — not visual identity.
It is designed to be extended via Nuxt Layers:

// your-project/nuxt.config.ts
export default defineNuxtConfig({
  extends: ["vue-starter-template"],
})

CMS Base Layer

@shopware/cms-base-layer is registered in the base template and provides:

• 50+ CMS components — sections, blocks, elements
• Product listing components (product cards, sliders, filters)
• Base UI primitives (buttons, checkboxes, radio buttons, icons)
• Shopware-specific @nuxt/image provider with presets (productCard, productDetail, thumbnail, hero)
• UnoCSS design tokens and runtime support

Child layers can override specific CMS blocks by placing a same-named component in their own app/components/ directory — no need to copy the entire CMS implementation.

How Component Overrides Work

Components resolve by layer precedence — child layers win over parent layers.
The base template registers its components with priority: 2, which overrides the CMS base layer's defaults. Your child layer automatically gets the highest priority.

Component resolution order (highest priority first):
1. Your project          → app/components/
2. vue-starter-template  → app/components/ (priority: 2)
3. cms-base-layer        → Sw* prefixed components

To override a component, place a file with the same name in your project's app/components/ directory. That's it — no configuration needed.

Design Tokens

The color system uses semantic tokens organized by purpose:

brand-*           → brand-primary, brand-secondary, brand-tertiary + hover/pressed/on variants
surface-*         → surface, background, containers, on-surface, inverse
states-*          → info, success, warning, error + hover/pressed/container variants
overlay-*         → dark/light at 5 opacity levels
outline-*         → outline, variant, primary, disabled, focus

UnoCSS configs chain through layers using mergeConfigs(). Each layer imports its parent's config and merges its overrides:

// your-project/uno.config.ts
import { mergeConfigs } from "@unocss/core";
import baseConfig from "vue-starter-template/.nuxt/uno.config.mjs";

export default mergeConfigs([baseConfig, {
  theme: {
    colors: {
      "brand-primary": "#B38A65",  // your brand color
      // everything else inherited
    },
  },
}]);

Extended: vue-starter-template-extended

The extended template (Lumora) is the proof that this architecture works.
It creates a fully rebranded storefront with only these source files:

File	What it does
nuxt.config.ts	Points extends to vue-starter-template
uno.config.ts	Overrides the color palette to Lumora brand
app/app.config.ts	Changes image placeholder color

That's it. Three files. Every page, component, composable, and integration is inherited from the base template. The entire Lumora brand identity comes from swapping the design tokens.
This is not a different architecture — it validates that the base layer supports real storefront customization without duplication.

⚠️ Note: In the StackBlitz demo, the base template is bundled in ./base-template/ so everything works self-contained. In a real project, you'd install vue-starter-template as a regular dependency.

What This Enables

For agencies and multi-storefront teams:

• Maintain one base, ship multiple branded storefronts
• Bug fixes and feature updates in the base propagate to all child projects
• Each storefront only contains its own customizations — no drift, no duplication

For individual projects:

• Start with a complete, working storefront instead of building from scratch
• Override only what you need — a single component, a page, or the entire design system
• Keep upgrading the base without merge conflicts in unchanged files

For the ecosystem:

• Shared evolution of core structure across the community
• Clear boundary between "Shopware provides" and "you customize"
• CMS blocks, pages, and layouts can be contributed and shared as layers