Create a new theme

A theme controls how a storefront looks and behaves. You can override any twig template, ship your own SCSS, add CMS elements, and expose settings to the admin, without touching the hostware core. Each sales channel picks one theme, so a single hostware installation can serve a completely different look on every storefront.

To spin up a new theme, drop a directory under custom/themes/<vendor>/<name> with a composer.json, activate it from the command line, then assign it to a sales channel.

Where a theme lives

Every theme sits at custom/themes/<vendor>/<name>. The vendor and name segments become the theme's identity and appear in asset URLs. Use your own vendor slug for third-party themes; the hw vendor is reserved for the hostware team.

Inside the theme directory, only composer.json is required. Everything else is opt-in:

custom/themes/hw/mytheme/
├── composer.json           required
├── config.xml              admin-configurable options (optional)
├── public/
│   ├── css/
│   │   ├── style.scss      SCSS entry the compile pipeline reads
│   │   └── style.min.css   fallback for storefronts before the first admin save
│   ├── js/                 theme JavaScript, served at /themes/<vendor>/<name>/js/*
│   └── img/                theme images, served at /themes/<vendor>/<name>/img/*
├── resources/
│   └── views/
│       └── storefront/     mirror any core template path to override it
└── Cms/
    └── Elements/           custom CMS elements (optional)

The composer.json

Two things make a directory a theme: the type laravel-theme, and an extra.theme block. Everything else is metadata the admin shows on the theme card.

{
  "name": "hw/mytheme",
  "description": "My theme for hostware storefront",
  "type": "laravel-theme",
  "version": "1.0.0",
  "license": "proprietary",
  "extra": {
    "theme": {
      "parent": "",
      "active": true
    }
  }
}

Set extra.theme.parent to another theme's vendor/name to inherit all its files as a base you extend. Leave it empty for a standalone theme.

Register and activate

hostware discovers a theme by scanning composer files, but it only creates a database row and lets sales channels pick it after it is activated.

1. Run php artisan theme:list. If your theme is missing, the composer.json is invalid or the type is wrong.

2. Run php artisan theme:activate <vendor>/<name>. For the example above that is php artisan theme:activate hw/mytheme.

3. Run php artisan theme:cache only when new twig files under resources/views/ refuse to resolve.

Assign the theme to a sales channel

A theme has no effect until it is picked by a sales channel. Open Administration > Sales Channels, edit the target channel, switch to the Theme tab, choose the theme and save. Saving triggers the SCSS compile immediately.

What to build next

The theme system has one entry point per capability. Read the piece that matches what you are building.

• Templates. Structure for the namespaces and how the resolver picks a version. Extending a template file for the block-by-block override pattern.

• Colours, fonts and radii. Compile theme SCSS with brand settings for the SCSS pipeline and the branding form integration.

• Admin-facing settings. Theme configuration via config.xml for tabs, fields and how templates read the saved values.

• Curated brand presets. Customization packages for the one-click "restore defaults" option.

• CMS content blocks. Add a CMS element from a theme for your own reusable page sections.

• Images, JavaScript, fonts. Ship images, JavaScript and other theme assets for the URL conventions and cache buster.

• Reference. Twig helpers a theme uses lists the functions and context variables available in every template.

• Dev loop. Develop and debug a theme locally covers the SCSS watcher, cache clearing, and the top mistakes that hide changes.