alizharb/laravel-themer
Laravel Themer is an enterprise-grade theme management package for Laravel and TALL stack apps. It offers per-theme Vite builds, NPM workspaces, theme-aware view overrides, Livewire 4 integration, interactive CLI wizards, safe theme cloning/activation, and a fast zero-IO production cache.
Architecture fit. Laravel Themer is a service-provider package that interposes on three resolution paths in a Laravel 11/12 application: Blade view lookup, Livewire component lookup, and Vite asset/manifest lookup. It layers a theme directory (themes/) over the application with a cascade of Active Theme → Parent Theme(s) → Application, plus a cached discovery manifest for zero-IO boot. That is a well-chosen seam: it means a theme is purely additive and the base application remains the fallback, so the package is a genuine no-op until a theme overrides something. This makes it architecturally low-commitment relative to packages that take over routing or the container.
The fit is strong for a specific class of problem: white-label/branded deployments, per-tenant or per-plan visual variants, seasonal or campaign skins, and admin-managed theme switching. It is weak for teams that only need two or three Blade layouts — the package's value is in inheritance, asset isolation, and lifecycle tooling, not in layout swapping, and adopting it for a small need imports a large surface area.
Integration feasibility. Composer install plus php artisan themer:install (interactive: publishes config/themer.php, creates themes/, optionally patches vite.config.js with themerLoader). Because the installer modifies vite.config.js, treat that step as a reviewed change rather than an accepted prompt. The heavier integration cost is not the package — it is the per-theme package.json + vite.config.js model, which changes your build topology from one bundle to N bundles. That is the real project, and it should be scoped as frontend-platform work, not as a dependency bump.
Prerequisites are narrow and worth confirming early: Laravel 11/12, Vite, Blade, and Livewire 4 for the Livewire-specific value. An Inertia/React or Vue SPA frontend would forfeit most of the benefit, since the cascade is view-and-component oriented.
Technical risk. Ranked:
laravel-modular, laravel-modular-livewire, laravel-modular-filament, laravel-hooks, filament-themer-luncher) from the same author. This is a one-person ecosystem in pre-adoption. There is no community corpus to debug against. MIT licensing is the mitigation — fork-and-own is a viable, cheap fallback given the codebase is PHPStan-clean and conventionally structured — but that must be an explicit budget line, not an assumption.theme:activate switches globally and Themer::forTheme() is ephemeral. The theme:name route middleware is the multi-tenant lever. If the target is one process serving many tenants with different themes, this needs a spike before commitment — the production cache is a single serialized manifest, and correctness depends on per-request resolution overriding a global default.theme:refresh/theme:cache runs. This is a deploy-pipeline dependency and a classic stale-cache incident.layouts::, pages::) and theme Livewire component registration can shadow existing app or vendor components. Namespace collision is a testable, containable risk.Key questions. (1) What is the maintainer's stated support window and major-version policy, and is there any commitment beyond best-effort? (2) Does the production cache invalidate correctly across a blue/green or rolling deploy where old and new code run concurrently against one manifest? (3) For multi-tenant use, what is the documented pattern for per-request theme selection, and is there a supported test proving isolation under concurrency? (4) How does theme:preview interact with authentication and caching layers — signed, expiring URLs are a surface that needs a security review. (5) What is the actual build-time and artifact-storage cost of N independent Vite builds in CI? (6) Is laravel-modular a hard dependency or only for modular discovery — i.e. can we adopt Themer without the sibling ecosystem?
Stack fit. Assumes Laravel 11/12, Blade, Vite, and (for the differentiating features) Livewire 4. Optional adjacencies: laravel-modular only if themes must be discovered inside modules — treat it as opt-in and defer it; filament-themer-luncher only if an admin UI for switching is a product requirement rather than a developer convenience. Adopting the whole sibling set at once multiplies bus-factor exposure for marginal gain.
Migration path. The cascade makes incremental adoption genuinely viable, and the plan should exploit that:
package.json + vite.config.js and the themerLoader for that one theme. Measure build time and artifact count before generalizing.theme:check for circular and missing parents.theme:cache/theme:refresh into the deploy pipeline, theme:check and theme:doctor into CI, and theme:preview into QA.Compatibility. Pin to an exact minor, not a caret range — with a single maintainer, an unattended composer update is an unowned risk. Run the PHPStan-clean signal as a proxy for internal quality, but verify against your Livewire and Laravel versions rather than the advertised matrix. Verify that themer:install's vite.config.js patch survives your existing Vite customization, and re-apply it manually if it does not.
Sequencing principle. Theme content migration is reversible and cheap; build-topology and deploy-pipeline changes are not. Therefore: views first, assets second, cache-in-CI third, and modular/Filament integration last — or never. Keep the base application rendering correctly without the package at every phase so a rollback is a config flip rather than a revert.
Maintenance. The dominant cost is ownership risk, not engineering effort. One maintainer, 8 stars, 0 dependents, and a release cadence that depends on a single person's availability. The realistic posture is vendored-adjacent: budget a few days per year for tracking upstream, and pre-agree that if the maintainer goes quiet, the team forks and carries it internally. The MIT license and conventional package structure make that fork cheap; the informal ecosystem coupling to laravel-modular makes it less cheap if you adopted the siblings. Do not adopt the siblings without need.
Support. Documentation lives in docs/ and a published site, plus a Laravel Boost skill and AI-assistance guidelines. That is unusually good for the maturity level, but it is author-written documentation, not community-validated. There is no commercial support, no SLA, no StackOverflow corpus, no third-party tutorials. Debugging unfamiliar behavior means reading the source. Realistically, one engineer should be designated as the internal owner and should read the theme resolution and cache code end-to-end during Phase 0 — a half-day investment that pays for itself the first time a deploy serves a stale manifest.
Scaling. The zero-IO cached manifest is the package's strongest operational property: boot cost does not grow with theme count or inheritance depth, which is the right design for a large theme library. The scaling costs sit elsewhere and are real: N independent Vite builds multiply CI wall-clock and CDN artifact paths; NPM workspaces save disk but introduce lockfile-per-theme drift that someone must own; and every additional theme is another manifest to keep valid, more theme:check surface, and more combinations for the diagnostics commands to reason about. Practical guidance: keep the theme count small and the inheritance shallow, and measure build time at three themes before assuming the model scales to twenty.
Failure modes. Worth naming explicitly and mapping to detection:
theme:refresh as a mandatory deploy step; theme:status as a post-deploy check.theme:check in CI.theme:doctor; a route-level smoke test per active theme.theme:preview before enabling in production.Ramp-up. For a competent Laravel developer, the interactive wizards and command surface get them productive in a day or two. The genuinely new mental models are the resolution cascade (which file wins) and the cache lifecycle (when production stops seeing the filesystem). Both are learnable but neither is obvious from the README, and there is no community material to fall back on — so plan a short internal write-up and a runbook covering "theme not updating in production," because that will be the first support ticket. Total onboarding cost: low for developers, moderate for the team that now owns a build pipeline with N bundles and a new deploy step.
How can I help you explore Laravel packages today?