README

A powerful and flexible Laravel package for theme management with seamless Vite integration.

✨ Features

🎨 Easy Theme Management - Add, list, and remove themes with simple Artisan commands 🛠️
⚡ Vite Integration - Full Vite support with hot reload and optimized builds ⚡️🔥
🔄 Inline Asset Rendering - Render CSS/JS assets inline for performance optimization 🚀
📁 Flexible Directory Structure - Customize theme directories via configuration 🗂️
🎯 Global Helper Functions - Access themes anywhere with the theme() helper 🧩
🧩 Blade Directives - Convenient Blade directives for theme integration ✨
🚀 Redis Caching - Optimized performance with Redis caching support ⚡️🧠
📦 Auto-Discovery - Automatic service provider registration ✅

📦 Installation

Install the package via Composer:

composer require rdcstarr/laravel-themes

⚙️ Required Setup

💡 Important: The Vite configuration is regenerated depending on which directories you change in config/themes.php.

If you only change themes.directories.build (the public/build path), you can update the Vite configuration without reinstalling themes by running php artisan theme:publish-vite

This updates Vite entries and build paths only.

If you change themes.directories.resources (the resources/themes path) — for example where theme views, CSS/JS and images live — you must run php artisan theme:install

theme:install validates and (re)creates theme resources and the Vite setup and may overwrite generated files.

Install the theme package (required first step):
```
php artisan theme:install
```

Publish the configuration file (optional):

php artisan vendor:publish --tag=theme-config

🛠️ Artisan Commands

🚀 Install Theme Package (required first):

php artisan theme:install [--force] [--manifest] [--tailwind]

Sets up the default theme and publishes Vite configuration files.

🎨 Add a New Theme:

php artisan theme:add {theme-name} [--manifest] [--tailwind]

Creates a complete theme structure with CSS, JS, views, and images directories. Use --manifest to also create a manifest.json file.

📋 List Available Themes:

php artisan theme:list

Shows all available themes with their paths.

🗑️ Remove a Theme:

php artisan theme:remove {theme-name} [--force]

Deletes the specified theme. Use --force to skip confirmation.

📝 Create/Recreate Theme Manifest:

php artisan theme:manifest-publish {theme-name} [--force]

Creates or recreates a manifest.json file for an existing theme. Use --force to skip confirmation when overwriting.

📑 Manage Theme Manifest Fields:

# List all fields in a theme's manifest
php artisan theme:manifest {theme-name} list

# Add a new field interactively
php artisan theme:manifest {theme-name} add

# Add a field with specific parameters
php artisan theme:manifest {theme-name} add --key=about.title --label="About Title" --type=text

# Remove a field
php artisan theme:manifest {theme-name} remove [--key=field-key]

Manage custom fields in theme manifest files for dynamic content configuration.

⚡ Publish Vite Configuration:

php artisan theme:publish-vite [--force]

Updates the Vite configuration file with theme support.

🎯 Theme API

Basic Operations:

// Get the current theme instance 🧭
theme()

// Set the current theme 🎚️
theme()->set('theme-name');

// Get the current theme name 🏷️
theme()->name();

// Check if a theme exists ✅
theme()->exists('theme-name');

// Get all available themes 📚
theme()->getAll();

Path Helpers:

theme()->basePath();  // Base path for all themes
theme()->path();      // Current theme path
theme()->viewsPath(); // Views directory
theme()->jsPath();    // JavaScript file path
theme()->cssPath();   // CSS file path

Vite Integration:

theme()->viteJs();                // Vite JS entry point
theme()->viteCss();               // Vite CSS entry point
theme()->viteImages();            // Vite images directory
theme()->getBuildDirectoryPath(); // Build output directory
theme()->getHotFile();            // Hot reload file

🎨 Blade Directives

Theme Information:

{{-- Display current theme name --}}
@themeName

Asset Integration:

{{-- Standard Vite assets (requires Vite dev server or build) --}}
@vite(theme()->viteCss())
@vite(theme()->viteJs())

{{-- Standard Vite assets (requires Vite dev server or build) --}}
@viteCss // with auto path to theme()->viteCss()
@viteJs  // with auto path to theme()->viteJs()

{{-- Inline assets (injects CSS/JS directly into HTML) --}}
@viteCssInline
@viteJsInline

{{-- Custom inline assets --}}
@viteInline([theme()->viteCss(), theme()->viteJs()])

Images with Vite:

{{-- In your Blade templates --}}
<img src="{{ Vite::image('logo.png') }}" alt="Logo">

⚙️ Configuration

The config/themes.php file allows you to customize directories:

return [
    'default' => env('THEME_DEFAULT', 'default'),

    'directories' => [
        'resources' => 'themes', // complete path will be `./resources/themes`
        'build'     => 'themes', // complete path will be `./public/themes`
    ],
];

🔥 Vite Development

🏁 Start development server for a specific theme:

npm run dev --theme=my-theme

🏢 Build assets for production:

npm run build --theme=my-theme

Vite Configuration Features:

✅ Theme-specific hot reload files
✅ Automatic theme directory validation
✅ Asset path resolution
✅ Full page reload on view changes

📁 Theme Structure

Each theme follows this organized structure:

resources/themes/my-theme/
├── css/
│   └── app.css          # Main CSS file
├── js/
│   └── app.js           # Main JavaScript file
├── images/              # Theme images
└── views/               # Blade templates
    └── welcome.blade.php

🚆 Middleware Integration:

// Set theme based on your preferences
public function handle($request, Closure $next)
{
    theme()->set('theme_name' ?? 'default');

    return $next($request);
}

⚡ Performance Features

Redis Caching:

✅ Automatic caching when Redis is configured 🧠
✅ Theme existence checks cached for 30 seconds ⏱️
✅ Manifest files cached for 30 seconds 📦
✅ Asset content cached for 30 seconds 💾

Inline Asset Benefits:

✅ Reduces HTTP requests 🌐
✅ Eliminates render-blocking resources 🚫🧱
✅ Perfect for critical CSS/JS 🚀
✅ Automatic caching in production ✅

🧪 Testing

composer test

📖 Resources

Changelog for more information on what has changed recently. ✍️

👥 Credits

Rdcstarr 🙌

📜 License

License for more information. ⚖️

rdcstarr / laravel-themes

Maintainers

Details