Laravel Themer: multi-theme support for Laravel application

This Laravel Themer package adds multi-theme support to your application. This theme package improves any application while allowing the freedom to organize and maintain your app's views as you see fit. 

It provides WordPress style theme fallback support. You can create a child theme to extend any theme. So, the first Laravel will look for a view file in the child theme, if it is not found in the child theme, then it will look for it in the parent theme. If the view file is also not found in the parent theme, then it will look for it in the resources/views directory.

It also provides a simple authentication scaffolding for a starting point for building a Laravel application. And it also has preset for Bootstrap, Tailwind, Vue, and React. So, I believe it is a good alternative to the Laravel UI and Laravel Breeze package.

Features

Laravel themer package currently supports the following feature set.

1. Any number of themes

2. Fallback theme support (Wordpress style); It allows creating a child theme to extend any theme

3. Provides a simple authentication scaffolding similar to laravel/ui & laravel/breeze package

4. Provides frontend presets for bootstrap, tailwind, vue, and react

Installation and setup

You can install this package via composer using:

composer require qirolab/laravel-themer

The package will automatically register its service provider.

Almost Done. You can optionally publish a configuration file to your application using the following command.

php artisan vendor:publish --provider="Qirolab\Theme\ThemeServiceProvider" --tag="config"

These are the contents of the published config file:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Default Active Theme
    |--------------------------------------------------------------------------
    |
    | It will assign the default active theme to be used if one is not set during
    | runtime.
    */
    'active' => null,

    /*
    |--------------------------------------------------------------------------
    | Parent Theme
    |--------------------------------------------------------------------------
    |
    | This is a parent theme for the theme specified in the active config
    | option. It works like the WordPress style theme hierarchy, if the blade
    | file is not found in the currently active theme, then it will look for it
    | in the parent theme.
    */
    'parent' => null,

    /*
    |--------------------------------------------------------------------------
    | Base Path
    |--------------------------------------------------------------------------
    |
    | The base path where all the themes are located.
    */
    'base_path' => base_path('themes')
];

That's it. You are now ready to start theming your applications!

Usage

Creating a theme

To create a new theme, run the following command in the terminal:

php artisan make:theme

This command will ask you to enter theme name, CSS framework, js framework, and optional auth scaffolding.

Now, it will create a theme file in the base_path defined in the configuration. By default, it is base_path('themes'). So, it will create a new theme in the themes directory that is in the root path of the application.

Set the active theme

Working with themes is very straightforward. Use the following method to switch the theme.

// set active theme
Theme::set('theme-name');

Other useful Theme methods:

// get current active theme
Theme::active();

// get current parent theme
Theme::parent(); 

// clear theme. So, no theme will be active
Theme::clear(); 

// Get theme path
Theme::path($path = 'views'); 
//output: app-root-path/themes/active-theme/views

Theme::path($path = 'views', $themeName = 'admin'); 
//output: app-root-path/themes/admin/views

Using a Middleware to set a theme

A helper ThemeMiddleware is included out of the box if you want to define a Theme per route. To use it first register it in app\Http\Kernel.php:

protected $routeMiddleware = [
    // ...
    'theme' => \Qirolab\Theme\Middleware\ThemeMiddleware::class,
];

Now you can apply the middleware to a route or route-group. Eg:

// Example 1: set theme for a route
Route::get('/dashboard', '[email protected]')
    ->middleware('theme:dashboard-theme');


// Example 2: set theme for a route-group
Route::group(['prefix' => 'admin', 'middleware'=>'theme:admin-theme'], function() {
    // "admin-theme" will be applied to all routes defined here
});


// Example 3: set child and parent theme
Route::get('/dashboard', '[email protected]')
    ->middleware('theme:child-theme,parent-theme');

Asset compilation

After creating a new theme using the php artisan make:theme command, you will see that it has created a webpack.mix.js in the newly created theme. So, to compile the theme assets, you need to include the theme's webpack.mix.js in the webpack.mix.js located in the root path of the application.

// add this in the root `webpack.mix.js` 
require(`${__dirname}/themes/theme-name/webpack.mix.js`);

Now you can run the npm install and npm run dev command to compile theme assets. 

If you have multiple themes, then npm run dev or npm run watch command will compile all the included theme's webpack.mix.js. So, it may slow down the compilation process because it is going to look for changes in every theme.

So, to solve this problem modify the root webpack.mix.js with the following command:

let theme = process.env.npm_config_theme;

if(theme) {
   require(`${__dirname}/themes/${theme}/webpack.mix.js`);
} else {
  require(`${__dirname}/themes/theme-name/webpack.mix.js`);
  // add all theme's webpack.mix.js
}

Now, to compile a particular theme run the following command:

npm run dev --theme=theme-name

# or

npm run watch --theme=theme-name

# or

npm run production --theme=theme-name

If you see the theme's webpack.mix.js file, it has specified mix.setPublicPath("public/themes/theme-name"). This means it is going to compile the CSS, JS in the public/themes/theme-name directory. Of course, you can modify it however you want.

You can include the CSS and JS in the blade file like this:

<!-- Scripts -->
<script src="{{ asset('themes/theme-name/js/app.js') }}" defer></script>

<!-- Styles -->
<link href="{{ asset('themes/theme-name/css/app.css') }}" rel="stylesheet">

or using mix() function:

<!-- Scripts -->
<script src="{{ mix('js/app.js', 'themes/theme-name') }}" defer></script>

<!-- Styles -->
<link href="{{ mix('css/app.css', 'themes/theme-name') }}" rel="stylesheet">

Here themes/theme-name is the public directory path where mix-manifest.json is present. That mix-manifest.json is created on run npm run dev command.

Conclusion

This Laravel themer is a simple and light-weight package that adds multi-theme support to your Laravel project. It also provides frontend presets and authentication scaffolding for a starting point for building a Laravel project. That makes it a good alternative to laravel/ui & laravel/breeze. Try it yourself and give your opinion in the comment section.