shop-theme-development

name	shop-theme-development
description	Shop theme development in Bagisto. Activates when creating custom storefront themes, modifying shop layouts, building theme packages, or working with Vite-powered assets for the customer-facing side of the application.
license	MIT
metadata	{"author":"bagisto"}

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

1. Login to admin panel
2. Go to Settings → Channels
3. Edit channel and select your theme
4. 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

Writing the Blade itself? The blade-conventions skill carries the markup rules — : vs :: attribute binding, anonymous vs Vue-backed components, indentation, comment style, and where translations and view_render_event hooks go.

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:

1. Activating theme in channel settings
2. Visiting storefront pages
3. Checking responsive design
4. Verifying all shop functionality works
5. Testing hot reload during development