shop-theme-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Bagisto中的店铺主题开发涉及将自定义店铺前端主题打包为Laravel包。最终成果是一个可独立分发和维护的自包含包。

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

在以下场景启用此技能：

将自定义店铺前端主题创建为包
构建可分发的主题包
处理基于Vite的资源
自定义面向客户的页面
覆盖默认店铺模板

Bagisto Shop Theme Architecture

Bagisto店铺主题架构

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`

组件	用途	位置
Theme Configuration	定义可用主题	`config/themes.php`
Views Path	Blade模板文件	在主题配置中定义
Assets Path	CSS、JS、图片	在主题配置中定义
Theme Middleware	解析激活的主题	`packages/Webkul/Shop/src/Http/Middleware/Theme.php`
Theme Facade	管理主题操作	`packages/Webkul/Theme/src/Themes.php`

Key Configuration Properties

关键配置属性

php

// 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',
        ],
    ],
],

php

// 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

最终成果应是一个包含以下内容的完整包：

包内包含所有视图
包内包含所有资源
用于发布的服务提供者
用于资源编译的Vite配置

Step 1: Create Package Structure

步骤1：创建包结构

bash

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

bash

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

Step 2: Copy Complete Shop Assets

步骤2：复制完整的店铺资源

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

bash

undefined

复制所有店铺资源到你的包中，以获得完全控制权：

bash

undefined

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

复制店铺package.json以获取依赖

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

cp packages/Webkul/Shop/package.json packages/Webkul/CustomTheme/


这将为你提供：
- 基于Tailwind的完整CSS基础
- 所有JavaScript功能
- 店铺组件和布局
- 图片、字体和静态资源
- 完整的Blade模板结构
- 资源编译所需的依赖

Step 3: Add Custom Home Page (Boilerplate)

步骤3：添加自定义首页（模板）

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

blade

<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>

复制完成后，创建一个自定义首页以展示这是新主题：

文件：

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

blade

<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)

步骤4：创建自定义布局（可选）

Create your own master layout for complete control:

File:

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

blade

<!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>

创建自己的主布局以获得完全控制权：

文件：

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

blade

<!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

步骤5：创建服务提供者

File:

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

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');
    }
}

文件：

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

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

步骤6：配置自动加载

Update

composer.json

json

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

Run:

composer dump-autoload

更新

composer.json

：

json

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

运行：

composer dump-autoload

Step 7: Register Service Provider

步骤7：注册服务提供者

Add to

bootstrap/providers.php

php

Webkul\CustomTheme\Providers\CustomThemeServiceProvider::class,

添加到

bootstrap/providers.php

：

php

Webkul\CustomTheme\Providers\CustomThemeServiceProvider::class,

Step 8: Update Theme Configuration

步骤8：更新主题配置

File:

config/themes.php

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',
        ],
    ],
],

文件：

config/themes.php

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

步骤9：发布视图

bash

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

bash

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

Step 10: Clear Cache

步骤10：清除缓存

bash

php artisan optimize:clear

bash

php artisan optimize:clear

Step 11: Activate Theme

步骤11：激活主题

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

登录管理面板
进入设置 → 渠道
编辑渠道并选择你的主题
保存

Step 12: Build Assets

步骤12：构建资源

bash

undefined

bash

undefined

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.

npm run build


这将编译你的主题资源并创建构建目录。构建完成后，你的自定义主题将与你创建的自定义首页一起可用。

Vite-Powered Assets

基于Vite的资源

Step 1: Create Asset Configuration Files

步骤1：创建资源配置文件

Create in your package root:

File:

package.json

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

javascript

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

javascript

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

javascript

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

在你的包根目录创建以下文件：

文件：

package.json

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"
    }
}

文件：

vite.config.js

javascript

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,
            }),
        ],
    };
});

文件：

tailwind.config.js

javascript

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-/ }],
};

文件：

postcss.config.js

javascript

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

Step 2: Add to Bagisto Vite Config

步骤2：添加到Bagisto Vite配置

File:

config/bagisto-vite.php

php

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

文件：

config/bagisto-vite.php

php

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

Development Commands

开发命令

bash

undefined

bash

undefined

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

undefined

npm run build

undefined

Development Workflow

开发工作流

Option A: Symlink (Recommended)

选项A：符号链接（推荐）

Create symlink for real-time development without republishing:

bash

undefined

创建符号链接以进行实时开发，无需重新发布：

bash

undefined

Remove published views

删除已发布的视图

rm -rf resources/themes/custom-theme/views

Create symlink from package to resources

创建从包到resources的符号链接

ln -s $(pwd)/packages/Webkul/CustomTheme/src/Resources/views resources/themes/custom-theme/views

undefined

ln -s $(pwd)/packages/Webkul/CustomTheme/src/Resources/views resources/themes/custom-theme/views

undefined

Option B: Direct Package Development

选项B：直接包开发

Work directly in package and republish when needed:

bash

undefined

直接在包中工作，并在需要时重新发布：

bash

undefined

After making changes

更改后运行

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

undefined

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

undefined

Shop Layouts

店铺布局

Using Shop Layout

使用店铺布局

blade

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

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

blade

<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

属性	类型	默认值	描述
`has-header`	布尔值	true	包含头部导航
`has-feature`	布尔值	true	显示特色区域
`has-footer`	布尔值	true	包含页脚

Minimal Page Example

极简页面示例

blade

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

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

blade

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

    {{-- 无头部/页脚的内容 --}}
</x-shop::layouts>

Shop Blade Components

店铺Blade组件

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

组件	用法	描述
`<x-shop::accordion>`	可折叠区域	切换内容可见性
`<x-shop::breadcrumbs>`	导航路径	显示当前页面路径
`<x-shop::button>`	操作按钮	支持加载状态
`<x-shop::datagrid>`	数据表格	排序、筛选、分页
`<x-shop::drawer>`	滑出面板	位置：上/下/左/右
`<x-shop::dropdown>`	下拉菜单	位置：左上、右下等
`<x-shop::flat-picker.date>`	日期选择器	基于Flatpickr
`<x-shop::flat-picker.datetime>`	日期时间选择器	基于Flatpickr
`<x-shop::media.images>`	图片上传	支持多图片
`<x-shop::modal>`	对话框	头部、内容、页脚插槽
`<x-shop::quantity-changer>`	数量输入框	+/-按钮
`<x-shop::table>`	数据表格	可自定义表头/表体
`<x-shop::tabs>`	标签导航	位置：左/右/中
`<x-shop::shimmer.*>`	加载效果	骨架加载器

Custom Layouts

自定义布局

Creating Custom Layout

创建自定义布局

File:

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

blade

<!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>

文件：

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

blade

<!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>
    
    {{-- 为自定义布局手动加载资源 --}}
    @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

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

文件	用途
`config/themes.php`	主题配置
`config/bagisto-vite.php`	Vite资源配置
`packages/Webkul/Shop/src/Providers/ShopServiceProvider.php`	店铺包注册
`packages/Webkul/Shop/src/Http/Middleware/Theme.php`	主题解析
`packages/Webkul/Theme/src/Themes.php`	主题外观类
`packages/Webkul/Shop/src/Resources/views/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

修改主题配置后未清除缓存
注册包后忘记运行composer dump-autoload
未复制完整的店铺资源（视图和资源文件）
使用自定义布局时未手动加载@bagistoVite资源
在已发布的文件而非包源文件中工作
未设置符号链接以优化开发工作流

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

通过以下方式测试你的主题：

在渠道设置中激活主题
访问店铺前端页面
检查响应式设计
验证所有店铺功能正常工作
测试开发期间的热重载