Shop Theme Development

Overview

Shop theme development in Bagisto involves creating custom storefront themes packaged as Laravel packages. The end result is a self-contained package that can be distributed and maintained independently.

When to Apply

Activate this skill when:

Creating custom storefront themes as packages
Building theme packages for distribution
Working with Vite-powered assets
Customizing customer-facing pages
Overriding default shop templates

Bagisto Shop Theme Architecture

Core Components

Component	Purpose	Location
Theme Configuration	Defines available themes	`config/themes.php`
Views Path	Blade template files	Defined in theme config
Assets Path	CSS, JS, images	Defined in theme config
Theme Middleware	Resolves active theme	`packages/Webkul/Shop/src/Http/Middleware/Theme.php`
Theme Facade	Manages theme operations	`packages/Webkul/Theme/src/Themes.php`

Key Configuration Properties

// config/themes.php
'shop-default' => 'default',

'shop' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/shop/default',
        'views_path' => 'resources/themes/default/views',
        'vite' => [
            'hot_file' => 'shop-default-vite.hot',
            'build_directory' => 'themes/shop/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

Creating Shop Theme Package

Goal: Complete Self-Contained Package

The end result should be a complete package with:

All views inside the package
All assets inside the package
Service provider for publishing
Vite configuration for asset compilation

Step 1: Create Package Structure

mkdir -p packages/Webkul/CustomTheme/src/{Providers,Resources/views}

Step 2: Copy Complete Shop Assets

Copy all shop assets to your package to have full control:

# Copy complete shop assets folder
cp -r packages/Webkul/Shop/src/Resources/assets/* packages/Webkul/CustomTheme/src/Resources/assets/

# Copy complete shop views folder
cp -r packages/Webkul/Shop/src/Resources/views/* packages/Webkul/CustomTheme/src/Resources/views/

# Copy shop package.json for dependencies
cp packages/Webkul/Shop/package.json packages/Webkul/CustomTheme/

This gives you:

Complete CSS foundation with Tailwind
All JavaScript functionality
Shop components and layouts
Images, fonts, and static assets
Complete Blade template structure
Dependencies for asset compilation

Step 3: Add Custom Home Page (Boilerplate)

After copying, create a custom home page to show it's a new theme:

File: packages/Webkul/CustomTheme/src/Resources/views/home/index.blade.php

<x-shop::layouts>
    <x-slot:title>
        Custom Theme Home
    </x-slot>

    {{-- Hero Section --}}
    <div class="hero-section bg-gradient-to-r from-blue-600 to-purple-600 text-white py-20">
        <div class="container mx-auto px-4 text-center">
            <h1 class="text-5xl font-bold mb-6">
                Welcome to Our Store
            </h1>
            
            <p class="text-xl mb-8 opacity-90">
                Professional theme with modern design
            </p>
            
            <a href="{{ route('shop.search.index') }}" 
               class="bg-white text-blue-600 font-bold py-3 px-8 rounded-lg hover:bg-gray-100 transition duration-300">
                Start Shopping
            </a>
        </div>
    </div>

    {{-- Featured Products --}}
    <div class="container mx-auto px-4 py-16">
        <h2 class="text-3xl font-bold text-center mb-12">
            Featured Products
        </h2>
        
        <!-- Product grid -->
    </div>
</x-shop::layouts>

Step 4: Create Custom Layout (Optional)

Create your own master layout for complete control:

File: packages/Webkul/CustomTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load theme assets manually --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
    
    @stack('meta')
    @stack('styles')
</head>
<body class="{{ $bodyClass ?? '' }}">
    @if($hasHeader ?? true)
        @include('custom-theme::layouts.header')
    @endif
    
    <main class="main-content">
        {{ $slot }}
    </main>
    
    @if($hasFooter ?? true)
        @include('custom-theme::layouts.footer')
    @endif
    
    @stack('scripts')
</body>
</html>

Step 5: Create Service Provider

File: packages/Webkul/CustomTheme/src/Providers/CustomThemeServiceProvider.php

<?php

namespace Webkul\CustomTheme\Providers;

use Illuminate\Support\ServiceProvider;

class CustomThemeServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        // Publish views to resources/themes/custom-theme/views
        $this->publishes([
            __DIR__ . '/../Resources/views' => resource_path('themes/custom-theme/views'),
        ], 'custom-theme-views');
    }
}

Step 6: Configure Autoloading

Update composer.json:

"autoload": {
    "psr-4": {
        "Webkul\\CustomTheme\\": "packages/Webkul/CustomTheme/src"
    }
}

Run: composer dump-autoload

Step 7: Register Service Provider

Add to bootstrap/providers.php:

Webkul\CustomTheme\Providers\CustomThemeServiceProvider::class,

Step 8: Update Theme Configuration

File: config/themes.php

'shop-default' => 'custom-theme',

'shop' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/shop/default',
        'views_path' => 'resources/themes/default/views',
        'vite' => [
            'hot_file' => 'shop-default-vite.hot',
            'build_directory' => 'themes/shop/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
    'custom-theme' => [
        'name' => 'Custom Theme Package',
        'assets_path' => 'public/themes/shop/custom-theme',
        'views_path' => 'resources/themes/custom-theme/views',
        'vite' => [
            'hot_file' => 'custom-theme-vite.hot',
            'build_directory' => 'themes/custom-theme/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

Step 9: Publish Views

php artisan vendor:publish --provider="Webkul\CustomTheme\Providers\CustomThemeServiceProvider"

Step 10: Clear Cache

php artisan optimize:clear

Step 11: Activate Theme

Login to admin panel
Go to Settings → Channels
Edit channel and select your theme
Save

Step 12: Build Assets

# Navigate to package
cd packages/Webkul/CustomTheme

# Install dependencies
npm install

# Build assets for production
npm run build

This will compile your theme assets and create the build directory. After building, your custom theme will be ready to use with the custom home page you created.

Vite-Powered Assets

Step 1: Create Asset Configuration Files

Create in your package root:

File: package.json

{
    "name": "custom-theme",
    "private": true,
    "description": "Custom Theme Package for Bagisto",
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    },
    "devDependencies": {
        "autoprefixer": "^10.4.14",
        "axios": "^1.1.2",
        "laravel-vite-plugin": "^0.7.2",
        "postcss": "^8.4.23",
        "tailwindcss": "^3.3.2",
        "vite": "^4.0.0"
    }
}

File: vite.config.js

import { defineConfig, loadEnv } from "vite";
import laravel from "laravel-vite-plugin";
import path from "path";

export default defineConfig(({ mode }) => {
    const envDir = "../../../";

    Object.assign(process.env, loadEnv(mode, envDir));

    return {
        build: {
            emptyOutDir: true,
        },
        envDir,
        server: {
            host: process.env.VITE_HOST || "localhost",
            port: process.env.VITE_PORT || 5173,
            cors: true,
        },
        plugins: [
            laravel({
                hotFile: "../../../public/custom-theme-vite.hot",
                publicDirectory: "../../../public",
                buildDirectory: "themes/custom-theme/build",
                input: [
                    "src/Resources/assets/css/app.css",
                    "src/Resources/assets/js/app.js",
                ],
                refresh: true,
            }),
        ],
    };
});

File: tailwind.config.js

module.exports = {
    content: [
        "./src/Resources/**/*.blade.php",
        "../../../resources/themes/custom-theme/**/*.blade.php"
    ],
    theme: {
        container: {
            center: true,
            screens: { "2xl": "1440px" },
            padding: { DEFAULT: "90px" },
        },
        screens: {
            sm: "525px",
            md: "768px",
            lg: "1024px",
            xl: "1240px",
            "2xl": "1440px",
            1180: "1180px",
            1060: "1060px",
            991: "991px",
        },
        extend: {
            colors: {
                navyBlue: "#060C3B",
                darkGreen: "#40994A",
            },
            fontFamily: {
                poppins: ["Poppins"],
                dmserif: ["DM Serif Display"],
            },
        },
    },
    plugins: [],
    safelist: [{ pattern: /icon-/ }],
};

File: postcss.config.js

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
}

Step 2: Add to Bagisto Vite Config

File: config/bagisto-vite.php

'custom-theme' => [
    'hot_file' => 'custom-theme-vite.hot',
    'build_directory' => 'themes/custom-theme/build',
    'package_assets_directory' => 'src/Resources/assets',
],

Development Commands

# Navigate to package
cd packages/Webkul/CustomTheme

# Install dependencies
npm install

# Start dev server with hot reload
npm run dev

# Build for production
npm run build

Development Workflow

Option A: Symlink (Recommended)

Create symlink for real-time development without republishing:

# Remove published views
rm -rf resources/themes/custom-theme/views

# Create symlink from package to resources
ln -s $(pwd)/packages/Webkul/CustomTheme/src/Resources/views resources/themes/custom-theme/views

Option B: Direct Package Development

Work directly in package and republish when needed:

# After making changes
php artisan vendor:publish --provider="Webkul\CustomTheme\Providers\CustomThemeServiceProvider" --force

Shop Layouts

Using Shop Layout

<x-shop::layouts>
    <x-slot:title>
        Page Title
    </x-slot>

    {{-- Page content --}}
</x-shop::layouts>

Layout Props

Prop	Type	Default	Description
`has-header`	Boolean	true	Include header navigation
`has-feature`	Boolean	true	Show featured section
`has-footer`	Boolean	true	Include footer

Minimal Page Example

<x-shop::layouts
    :has-header="false"
    :has-footer="false"
>
    <x-slot:title>
        Minimal Page
    </x-slot>

    {{-- Content without header/footer --}}
</x-shop::layouts>

Shop Blade Components

Available Components

Component	Usage	Description
`<x-shop::accordion>`	Collapsible sections	Toggle content visibility
`<x-shop::breadcrumbs>`	Navigation trail	Show current page path
`<x-shop::button>`	Action buttons	Loading states supported
`<x-shop::datagrid>`	Data tables	Sorting, filtering, pagination
`<x-shop::drawer>`	Slide-out panels	Position: top/bottom/left/right
`<x-shop::dropdown>`	Dropdown menus	Position: top-left, bottom-right, etc.
`<x-shop::flat-picker.date>`	Date picker	Based on Flatpickr
`<x-shop::flat-picker.datetime>`	Date-time picker	Based on Flatpickr
`<x-shop::media.images>`	Image upload	Multiple images support
`<x-shop::modal>`	Dialog boxes	Header, content, footer slots
`<x-shop::quantity-changer>`	Quantity input	+/- buttons
`<x-shop::table>`	Data tables	Customizable thead/tbody
`<x-shop::tabs>`	Tab navigation	Position: left/right/center
`<x-shop::shimmer.*>`	Loading effects	Skeleton loaders

Custom Layouts

Creating Custom Layout

File: packages/Webkul/CustomTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load assets manually for custom layouts --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body>
    @if($hasHeader ?? true)
        @include('custom-theme::layouts.header')
    @endif
    
    <main>
        {{ $slot }}
    </main>
    
    @if($hasFooter ?? true)
        @include('custom-theme::layouts.footer')
    @endif
</body>
</html>

Complete Package Structure

packages/Webkul/CustomTheme/
├── src/
│   ├── Providers/
│   │   └── CustomThemeServiceProvider.php
│   └── Resources/
│       ├── assets/
│       │   ├── css/
│       │   │   └── app.css
│       │   ├── js/
│       │   │   └── app.js
│       │   ├── images/
│       │   └── fonts/
│       └── views/
│           ├── layouts/
│           │   └── master.blade.php
│           ├── home/
│           │   └── index.blade.php
│           ├── components/
│           └── ...
├── package.json
├── vite.config.js
├── tailwind.config.js
└── postcss.config.js

Key Files Reference

File	Purpose
`config/themes.php`	Theme configuration
`config/bagisto-vite.php`	Vite asset configuration
`packages/Webkul/Shop/src/Providers/ShopServiceProvider.php`	Shop package registration
`packages/Webkul/Shop/src/Http/Middleware/Theme.php`	Theme resolution
`packages/Webkul/Theme/src/Themes.php`	Theme facade
`packages/Webkul/Shop/src/Resources/views/components/*`	Shop components

Common Pitfalls

Not clearing cache after theme config changes
Forgetting to run composer dump-autoload after package registration
Not copying complete shop assets (views and assets)
Using custom layouts without manually loading @bagistoVite assets
Working in published files instead of package source files
Missing symlink setup for development workflow

Testing

Test your theme by:

Activating theme in channel settings
Visiting storefront pages
Checking responsive design
Verifying all shop functionality works
Testing hot reload during development