Theme Companion for Sylius

A powerful companion plugin for Sylius themes with asset management, build pipelines, and package management.

Compatibility

ℹ️ For Sylius 1.12, see our 1.x branch and all 1.x releases.

Installation

If you want to use our recipes, you can configure your composer.json by running:

Quick Start

1. Enable Theme Companion

Add need_companion: true to your theme's composer.json:

That's it! Your theme is now enhanced with Theme Companion features and will appear in the channel configuration, even if it's a packaged theme outside the themes/ folder.

💡 See it in action: Check out the naked theme example

2. Add Assets (Optional)

Place your assets in the assets/ folder in your theme:

Assets are automatically available via Symfony Asset Mapper:

📁 Example: See the complete structure in naked theme

3. Configure Build Pipeline (Optional)

For SCSS, Tailwind, or other compilation needs, add a build pipeline:

Supported runners: sass, tailwind, copy

📦 Examples:

• SCSS compilation: original theme
• Tailwind config template: tailwind.config.js.twig

Commands

Debug Themes

Install Dependencies

Build Assets

Configuration Options

Naming Convention

The name of your theme will be used in two main places:

• Asset Mapper prefix (e.g., {{ asset('@MonsieurbizSyliusFooTheme/css/style.css') }})
• Parameter name (e.g., %theme_companion.monsieurbiz_sylius_foo_theme.assets_path%)

If the name of your theme is monsieurbiz/sylius-foo-theme in the composer.json file:

Custom Prefix

Control the Asset Mapper prefix:

📄 Example: naked theme

JavaScript Dependencies

Manage JS packages with Asset Mapper:

Then create assets/package.json containing your dependencies:

📄 Example: naked theme dependencies

Theme Variables

Pass variables to Twig templates:

Access in templates: {{ theme.getVar('twig', 'logo_text') }}

📄 Example: naked theme variables

Parent Themes

Inherit configuration from another theme:

Child themes inherit build pipelines, dependencies, and variables from parent themes.

📄 Example: quartz theme

Asset Mapper Configuration

Add additional Asset Mapper paths or exclude patterns:

📄 Example: original theme

Build Pipeline Options

SCSS/Sass Compilation

Tailwind CSS

Copy Files

📄 Example: original theme build pipeline

Examples

Full working examples are available in the examples/themes/ directory:

• naked - Simple theme with static CSS and Alpine.js

  • Shows basic asset structure
  • Asset Mapper integration
  • JavaScript dependencies

• original - SCSS compilation with Asset Mapper

  • Build pipeline with Sass runner
  • JavaScript dependencies
  • Font file copying

• quartz - Theme inheritance

  • Parent theme example
  • Shows configuration merging
  • SCSS variables override

• naked-override - Template overriding

  • Minimal override example
  • Child theme pattern
• packaged - Theme as Composer package
  • Distribution example
  • Shows package-based themes

Development Tools

Theme Switcher (Dev Mode Only)

Quickly switch themes during development without modifying the database:

This is only available in development mode and requires the dev routes to be imported.

Debug Toolbar

View current theme information in the Symfony profiler toolbar. The toolbar shows:

• Active theme name
• Theme prefix
• Parent themes
• Build pipeline status

Contributing

We welcome contributions! Please see our contribution guidelines for details.

License

This plugin is under the MIT license. See the LICENSE file for details.

Credits

Developed by Monsieur Biz, expert Sylius agency.