Creating a TruCMS Theme

TruCMS has one public theme, Echo, built to look very different from site to site through its options. Before you write a theme, check whether options, a website template or a few view overrides already get you there. When you do need your own markup, build a child theme of Echo.

Choose the lightest tool

Anatomy of a theme

resources/themes/
  default/        shared parent: static images and the CKEditor build; every theme extends it
  admin/          the admin panel (extends default)
  echo/           the public site (extends default)
    theme.json    manifest + the theme-option schema ("defaults")
    layouts/      app-layout, fullwidth-layout, guest-layout, error-page
    components/   header and footer presets, breadcrumbs, cookie banner ...
    menu/ pages/ blog/ posts/ shortcodes/ widgets/ user/ auth/ emails/ errors/
    vendor/       overrides of package and module views
    page-templates/   the section library used by the page builder
    assets/sass, assets/js, assets/images

The manifest

resources/themes/echo/theme.json (without the defaults block)

{
    "name": "echo",
    "extends": "default",
    "asset-path": "themes/echo",
    "category": "front",
    "require": "1.0.0",
    "description": "The default TruCMS frontend theme.",
    "version": "2.0.0",
    "defaults": { "...": "theme option schema" }
}

Theme manifests are cached. After adding or editing a theme.json, run php artisan theme:refresh-cache.

How the active theme is chosen

• The public theme is config('dotartisan.front_theme'), set from APP_FRONT_THEME (default echo). The FrontTheme middleware activates it on every public route. There is no theme switcher in the admin; change the environment value and clear the config cache.
• The admin theme is the admin_theme setting (default admin), activated by AdminTheme.
• Code outside a request (Artisan commands, queued jobs, async widgets) runs without either middleware. Call Theme::set('echo') yourself before rendering theme views there.

How views resolve

The active theme's folder and every parent are added to Laravel's view paths, so view('pages.show') finds resources/themes/{active}/pages/show.blade.php first, then the parent's copy. A child theme only contains the files it changes.

Namespaced module views follow the same idea: booking::front.services is looked up first in resources/themes/{active}/vendor/booking/front/services.blade.php, then in the module. That is how a theme restyles a plugin without touching it.

Build a child theme of Echo

1. Create the folder and manifest

   resources/themes/harbor/theme.json

   {
       "name": "harbor",
       "extends": "echo",
       "asset-path": "themes/harbor",
       "category": "front",
       "require": "1.0.0",
       "description": "Harbor: a child theme of Echo.",
       "version": "1.0.0",
       "defaults": {}
   }

   Then copy Echo's whole defaults object into yours. The option schema is not inherited: ThemeOptionsSchema reads only the active theme's theme.json, so an empty defaults leaves you with a bare fallback options screen and theme_option() without defaults.

2. Override only what you change

   Copy a view from Echo to the same relative path in harbor/ and edit it, for example components/headers/logo-left.blade.php or vendor/booking/front/partials/summary.blade.php. Keep the variables and slots the original expects.

3. Give it a stylesheet entry

   Create resources/themes/harbor/assets/sass/app.scss (it can start by importing Echo's Sass) and add it to the input list in the root vite.config.js. The theme-option compiler looks for resources/themes/{theme}/assets/sass/app.scss in the Vite manifest; without it, saved options never reach your theme's CSS. Echo's layout loads resources/themes/echo/assets/sass/app.scss directly, so also override layouts/app-layout.blade.php (and the other layouts you use) to load your entry.

4. Static assets

   Put images in resources/themes/harbor/assets/images and add a copy target to vite.config.js like Echo's, so they land in public/themes/harbor.

5. Activate

   php artisan theme:refresh-cache
   # set APP_FRONT_THEME=harbor in .env, then:
   php artisan optimize:clear
   npm run build

   Open Appearance → Theme options, save once, and use Advanced → Regenerate Theme CSS after later builds.

What is tied to the theme name

Plan for these before switching a live site to a new theme name:

Theme helpers in Blade

Layouts available to plugins

Plugin views should wrap themselves in the layout components rather than extend a theme file directly, so they work under any theme: