Theme inheritance is one of Shopware’s most elegant architectural decisions. Instead of forcing developers to duplicate entire file trees or rely on fragile !important overrides, Shopware provides a structured, multi-layer inheritance system that respects update safety while granting granular control over appearance and behavior. In Shopware 6.7, this system was further refined for predictability, performance, and stricter schema validation. Understanding how it works is essential for building maintainable storefronts.

The Core Architecture: A Three-Domain Inheritance Chain

Theme inheritance in Shopware 6.7 operates across three synchronized domains: configuration, styling (SCSS), and markup/behavior (Twig + JavaScript). Each domain follows a parent-to-child resolution order, but they resolve independently until compilation merges them into runtime-ready assets.

At compile time, Shopware traverses the inheritance chain, flattens variable mappings, optimizes CSS selectors, bundles Twig blocks, and merges JS configuration objects. The result is a clean, optimized output that contains only what your theme actually overrides.

Configuration Layer: shopware.theme.json

Every theme must declare its parent using the extends key in config/your-theme/shopware.theme.json. Shopware 6.7 enforces strict schema validation, requiring proper inheritance chains and rejecting circular references.

{
  "title": "My Custom Theme",
  "description": "Extends storefront with custom variables and blocks",
  "extends": "storefront",
  "base-theme": null
}

The extends value can point to a base theme (storefront, minimal, or any third-party parent). Shopware resolves the chain at runtime, but theme compilation is mandatory for changes to take effect. You never manually merge JSON files; the CLI handles resolution order and validation.

SCSS Variable Inheritance & Resolution Order

Shopware’s styling layer relies on a compiled variable map. When you define a SCSS variable in your child theme, it automatically overrides inherited values based on a strict precedence chain:

  1. Base theme defaults (src/Resources/sass/base-theme/...)
  2. Parent theme overrides
  3. Child theme local variables (src/Resources/sass/your-theme/variables.scss)
  4. Store backend configuration (UI customizer)
  5. Inline styles (last resort)
/* src/Resources/sass/my-theme/variables.scss */
$sw-theme-primary: #2d5aa0;
$sw-theme-border-radius: 12px;
$sw-font-family-base: 'Inter', sans-serif;

/* No need to re-import parent files. Shopware automatically chains them. */

In 6.7, variable mapping is more strict. Undeclared variables in the inheritance chain are resolved to their original base values. If a parent theme introduces a new variable without defaulting it, your child theme will still inherit it unless explicitly overridden or disabled.

Twig Block Inheritance: Structural Overrides

Twig block inheritance in Shopware 6.7 works through block aggregation rather than traditional template extends. During compilation, Shopware scans all files in the inheritance chain, merges blocks by name, and generates a flat Twig structure at runtime.

You override blocks by creating a file with the exact same path as the parent theme:

{# src/Resources/views/storefront/layout/footer.html.twig #}
{% block layout_footer_content %}
    <div class="custom-footer">
        {{ parent() }}
        <p>Built with Shopware 6.7 inheritance</p>
    </div>
{% endblock %}

Key behavior in 6.7:

  • parent() calls the aggregated parent block, not just the immediate file.
  • Blocks are resolved depth-first; deeper themes take precedence.
  • Conditional logic or @extends directives outside theme files may break inheritance chains and should be avoided in storefront overrides.

JavaScript Configuration Merging

Shopware 6.7 improved JS config inheritance using a dedicated ThemeConfig service. Extensions and child themes can merge settings without modifying core modules:

// src/Resources/app/my-theme/config/theme.config.js
import { register } from 'shopware';

register('theme-config', () => ({
    components: {
        SwFooter: {
            customText: true,
            socialIconsSize: 24
        }
    },
    plugins: {
        SwSearchSuggestion: {
            maxSuggestions: 15
        }
    }
}));

Config merging follows the same inheritance order as SCSS. Deep objects are merged recursively, not replaced entirely. This prevents accidental loss of parent configurations.

Compilation & Runtime Behavior

Theme changes never take effect immediately in Shopware 6.7. You must compile:

bin/themes --compile all
bin/plugins --regenerate  # Only if your theme uses plugin assets
php bin/console theme:dump storefront

During compilation, Shopware:

  1. Validates the inheritance chain for conflicts or missing parents
  2. Resolves and flattens SCSS variables into CSS custom properties
  3. Aggregates Twig blocks into optimized files
  4. Merges JS configs and tree-shakes unused modules
  5. Writes output to public/theme-assets/

Invalid themes will fail compilation with detailed stack traces. This is a major improvement over earlier versions where broken inheritance would silently fall back to defaults.

Best Practices for Shopware 6.7

  • Limit nesting depth: Stay within 2–3 inheritance levels. Deep chains increase compile time and debugging complexity.
  • Always use CLI commands: Never edit compiled CSS or JS directly. Cache invalidation requires recompilation.
  • Leverage the debug plugin: Enable theme:debug to visualize inheritance resolution, variable sources, and block origins.
  • Avoid SCSS imports in child themes: Shopware auto-chains variables. Manual imports cause duplicate compilation and conflict errors.
  • Test with cache warmup: Run bin/console cache:warmup after theme changes to ensure production readiness.

Conclusion

Theme inheritance in Shopware 6.7 is a mature, predictable system that balances developer flexibility with platform stability. By understanding the three-domain resolution chain, respecting compilation boundaries, and following inheritance best practices, you can build highly customized storefronts without sacrificing update compatibility. The framework’s strict validation and optimized asset pipeline make 6.7 one of the most reliable versions yet for theme development. Master these foundations, and your customizations will scale cleanly alongside Shopware’s evolution.