Laravel Themer Laravel Package

Product Decisions This Supports

• Dynamic Theming & Branding: Enhanced with PreviewTheme Middleware for secure theme previews (e.g., ?preview_theme=slug), enabling real-time client/stakeholder feedback without deployment. System Event Hooks in theme.json allow triggering migrations, seeds, or notifications (e.g., Slack alerts) when themes activate, critical for SaaS platforms with tenant-specific branding.
• Modular Frontend Architecture: Native Vite Integration eliminates legacy symlink workarounds, enabling seamless @vite tag usage in themed assets. Zero-IO Production Cache reduces theme-switching latency to near-instant, improving LCP for high-traffic apps (e.g., e-commerce seasonal promotions).
• Livewire 4 Integration: Safe Mode Fallback ensures Livewire components remain functional even if a theme’s ThemeServiceProvider fails, reducing risk during rapid theming experiments (e.g., dark mode A/B tests).
• Zero-Config Adoption: Interactive CLI Wizards and theme:dev auto-proxy slash dev onboarding time by 50% for non-technical stakeholders (e.g., designers creating theme variants).
• Roadmap Flexibility:
  • Multi-Tenancy: Combine PreviewTheme Middleware with spatie/laravel-multitenancy for isolated tenant previews.
  • Headless CMS: System Event Hooks can auto-generate themes from CMS webhooks (e.g., Contentful’s publish_webhook triggering theme:make).
  • Progressive Theming: Git Workspace Synchronization and .gitignore auto-generation streamline collaborative theming workflows (e.g., design agencies).
• Performance Optimization:
  • Zero-IO Cache reduces theme-switching overhead from O(n) filesystem scans to O(1) array lookups, critical for apps with 100+ themes (e.g., enterprise portals).
  • Isolated Linting (theme:lint) enforces consistency across themed assets without bloating CI pipelines.

When to Consider This Package

• Avoid if:
  • Your app uses static site generation (e.g., Laravel Vapor + Blade) or lacks a build pipeline (Vite/Webpack), as Native Vite Integration is now mandatory for full feature support.
  • You require runtime-generated assets (e.g., dynamic SVG icons) that conflict with the Zero-IO Cache’s pre-serialization model.
  • Your team prefers client-side theming (CSS variables) over server-rendered themes, as the package’s PreviewTheme Middleware and Safe Mode Fallback are server-side optimizations.
  • You’re on Laravel <10.x or PHP <8.1, as Laravel 13 Support and PHPStan compliance require these versions.
• Look elsewhere if:
  • You need fine-grained theme permissions (e.g., role-based theme access), as the PreviewTheme Middleware uses signed URLs/query params (not RBAC).
  • Your workflow relies on manual asset symlinking (e.g., custom Gulp tasks), as the Vite Integration deprecates legacy symlink workarounds.
  • You require theme versioning (e.g., rollback to v1.2.3 of a theme), as the Zero-IO Cache serializes themes into a single immutable array.

How to Pitch It (Stakeholders)

For Executives: *"v1.3.0 turns theming from a 6-month project into a 2-week sprint. Key upgrades:

• Instant theme previews (?preview_theme=slug) let marketers test brand variants without dev cycles.
• Auto-linting per theme ensures design consistency at scale (critical for global rollouts).
• Zero-IO caching cuts theme-switching latency by 90%, future-proofing for 10K+ concurrent users. For $0 in licensing, we match the theming speed of $100K custom builds. ROI: 3x faster A/B testing, 50% fewer frontend merge conflicts."*

For Engineering: *"v1.3.0 eliminates our biggest theming pain points:

• Vite Integration: No more hacky symlinks—just @vite('resources/themes/my-theme/assets/app.css').
• Safe Mode Fallback: Broken ThemeServiceProvider? App stays up with the default theme.
• Zero-IO Cache: Themes now boot in <5ms (vs. 500ms+ before). Add this to your bootstrap/app.php:

  $app->singleton(\AlizHarb\Themer\ThemeManager::class, fn() => new \AlizHarb\Themer\ThemeManager(
      cache()->rememberForever('themes', fn() => ThemeManager::resolveCachedThemes())
  ));
  

• System Hooks: Need to run php artisan db:seed when a theme activates? Just add it to theme.json:

  { "after_activate": ["php artisan db:seed --class=EcommerceSeeder"] }
  

Upgrade path: Run php artisan theme:upgrade—it auto-migrates your themes to the new structure."*

For Design: *"You can now:

• Preview themes live before handing off to devs (no more ‘it looks different in production’ surprises).
• Lint your theme’s CSS/JS with one command (php artisan theme:lint my-theme)—fixes formatting issues before PRs.
• Use Vite’s HMR in your theme’s dev server (php artisan theme:dev). Changes reflect instantly. Pro tip: Use the interactive wizard (php artisan theme:make) to scaffold a new theme—it asks all the right questions about your design system."*