Acme CustomBlocks

A reference package that shows how to author custom blocks, sections, and presets for Bagisto Visual. Use it as a worked example, or scaffold your own package from the bagistoplus/customblocks-template repository.

What this package contains

It registers a single @customblocks/hero block. The service provider discovers blocks, sections, and presets at boot, then injects a Tailwind stylesheet into the storefront head via the bagisto.shop.layout.head.after event. The stylesheet is built by Vite (with laravel-vite-plugin) into the host application's public/vendor/customblocks/ directory.

Layout

src/
  ServiceProvider.php        Registers views, translations, asset publishing, and block discovery
  Blocks/
    Hero.php                 Example SimpleBlock with a single text setting
resources/
  views/
    blocks/hero.blade.php    Hero block markup
    style.blade.php          Vite tag injected into the storefront head
  assets/css/index.css       Tailwind entry
vite.config.ts               Tells Vite to emit into <app>/public/vendor/<slug>/
composer.json                Declares the service provider for Laravel package discovery
package.json                 Vite and Tailwind dev dependencies

The service provider also calls Visual::discoverSectionsIn(...) and Visual::discoverPresetsIn(...). You can create src/Sections/ and src/Presets/ directories alongside src/Blocks/ and they will be picked up automatically.

Create your own package

1. Clone the template

git clone https://github.com/bagistoplus/customblocks-template packages/YourVendor/YourPackage
cd packages/YourVendor/YourPackage
rm -rf .git
git init

2. Configure the package

php configure.php

The script asks for the vendor, package name, and an internal slug, rewrites every placeholder across the package, and then deletes itself.

3. Install dependencies

composer install
npm install

4. Register the package with the Bagisto application

Bagisto's root composer.json already declares packages/*/* as a path repository, so dropping the package under that directory is enough. From the application root:

composer require yourvendor/your-package:*@dev
php artisan optimize:clear

Laravel package discovery picks up the service provider through extra.laravel.providers in the package's composer.json.

5. Build assets

From the package directory:

npm run dev      # development with HMR
npm run build    # production build

The output lands in the host application at public/vendor/<slug>/. The matching style.blade.php view tells the storefront where to find the built stylesheet and hot file.

6. Add a block

// src/Blocks/Banner.php
namespace YourVendor\YourPackage\Blocks;

use BagistoPlus\Visual\Blocks\SimpleBlock;
use BagistoPlus\Visual\Settings\Text;

class Banner extends SimpleBlock
{
    protected static string $type = '@yourpackage/banner';
    protected static string $view = 'yourpackage::blocks.banner';

    public static function settings(): array
    {
        return [
            Text::make('title', 'Title')->default('Hello'),
        ];
    }
}

Create the matching view at resources/views/blocks/banner.blade.php. The class is registered automatically by the Visual::discoverBlocksIn(...) call in the service provider, so no manual wiring is needed.