README

Laravel Themer is a robust, enterprise-grade theme management package for Laravel applications. It provides a seamless way to manage themes, including asset publishing, view overrides, Livewire 4 integration, and modular support. Designed for modern TALL stack applications, it simplifies the creation of multi-themed applications without the complexity.

✨ Features

• 🏗️ Independent Vite Builds: Per-theme package.json and vite.config.js for total asset isolation.
• 📦 NPM Workspaces: Zero-config workspace integration for shared dependencies and optimized storage.
• ⚡ Asset Shortcuts: Launch dev servers or build theme assets directly via theme:dev and theme:build.
• 🛠️ Theme Management: Create, clone, safe-delete, and activate themes with consistent --theme support.
• 🚀 Zero-IO Production Cache: High-performance architecture that evaluates deep inheritance chains and serializes them into a single fast-boot PHP array.
• ✨ Interactive Wizards: Beautiful CLI prompts for generating and activating themes using laravel/prompts.
• 🌈 Rich Metadata: Support for screenshots, tags, and management flags (removable, disableable) in theme.json.
• ⚡ Livewire 4 Integration: First-class support for Livewire components and layouts with theme-aware resolution.
• 🎨 View Overrides: Intelligent view resolution cascading from Active Theme -> Parent Theme -> Application.
• 🚀 Auto-Blade Discovery: Automatic registration of theme-specific Blade components and inheritance.
• 🏷️ Theme Versioning: Support for version metadata in theme.json for easier dependency mapping.
• 🚦 Ephemeral Switching: Temporarily switch themes for specific tasks using Themer::forTheme().
• 🛣️ Route Middleware: Enforce specific themes for routes or groups via middleware('theme:name').
• 🧩 Modular Support: Native integration with laravel-modular including dependency verification in theme:check.
• 🛡️ Hierarchy Guard: Built-in validation to detect circular dependencies, missing parents, and asset health.
• 🧭 Production Diagnostics: theme:doctor, theme:status, theme:debug, theme:graph, and theme:why expose theme health for teams and CI.
• 🧪 Theme Previewing: Generate inactive-theme preview URLs with optional signed expiration using theme:preview.
• 🎛️ Design Tokens: Store brand tokens in theme.json and expose them with theme_token(), theme:tokens, and @themeTokens.
• 🧠 Laravel Boost Ready: Ships Boost guidelines and a theme-development skill for AI-assisted workflows.
• 🔧 Artisan Commands: A comprehensive suite of commands (make, npm, dev, build, clone, delete, list, check, cache, lint) to natively manage themes.

📚 Documentation

For full documentation, please visit alizharb.github.io/laravel-themer or browse the docs/ directory.

For copy-ready release notes, see RELEASE_NOTES_1.4.0.md.

📦 Installation

Install the package via Composer:

composer require alizharb/laravel-themer

Quick Start (Recommended)

Run the installation command to automatically set up Laravel Themer:

php artisan themer:install

This interactive command will:

• ✅ Publish the configuration file (config/themer.php)
• ✅ Create the themes directory (default: themes/)
• ✅ Optionally configure vite.config.js with the themerLoader for automatic theme asset bundling

Manual Configuration

If you prefer manual setup or need more control, see the Installation Guide for detailed instructions on:

• Publishing configuration files
• Setting up Vite integration
• Configuring theme paths and discovery rules

🔗 Related Packages

Laravel Themer is part of a comprehensive modular ecosystem for Laravel applications:

These packages work seamlessly together to provide a complete modular development experience.

📖 Usage

Creating a Theme

Generate a new theme with a standard directory structure:

php artisan theme:make "Dark Theme"

Managing Dependencies

Install packages into a theme workspace directly from the root:

php artisan theme:npm --theme=dark-theme install lodash

Developing Assets

Launch a dedicated Vite dev server for your theme:

php artisan theme:dev --theme=dark-theme

Cloning & Deletion

Safe and fast lifecycle management:

# Duplicate an existing theme
php artisan theme:clone "Summer Edition" --theme=dark-theme

# Safe removal (respects 'removable' flag)
php artisan theme:delete --theme=summer-edition

Activating a Theme

Switch the active theme globally:

php artisan theme:activate dark-theme

Production Diagnostics

Inspect and validate your theme system:

php artisan theme:doctor
php artisan theme:status
php artisan theme:debug dark-theme --json
php artisan theme:graph
php artisan theme:why dark-theme

Previewing Themes

Generate a preview URL for an inactive theme:

php artisan theme:preview dark-theme --signed --expires=30

Design Tokens

Expose theme-specific brand tokens:

php artisan theme:tokens dark-theme --css

@themeTokens

Livewire Integration

The package automatically registers Livewire components within your theme.

php artisan make:livewire Header --theme=dark-theme

🧪 Testing

We strictly enforce testing. Use the provided test suite to verify your themes:

vendor/bin/pest

💖 Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel Themer development. If you are interested in becoming a sponsor, please visit the Laravel Themer GitHub Sponsors page.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING for details.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🌟 Acknowledgments

• Laravel: For creating the most elegant PHP framework.
• Spatie: For setting the standard on Laravel package development.

🔒 Security

If you discover any security-related issues, please email Ali Harb at harbzali@gmail.com.

📄 License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by Ali Harb