rizky-dhani/filabuilder
Filabuilder is a Laravel package that extends Filament with reusable builder components, letting you assemble forms, layouts, and UI blocks faster. It aims to cut boilerplate so you can compose admin panels and resources with less custom code. Early-stage, minimal adoption, so review the source befo...
FilaBuilder is a Filament plugin that mounts a GrapesJS canvas inside the admin panel so editors can drag blocks (HeroBlock, TextBlock, CtaBlock ship in the box) onto a page and save the result. For a Laravel developer, the day-to-day job is three things: wire the builder into a Filament panel, define the block types your content actually needs, and render saved pages on the front end.
Install and publish
composer require rizky-dhani/filabuilder
php artisan vendor:publish --provider="RizkyDhani\FilaBuilder\FilaBuilderServiceProvider"
php artisan migrate # only if you use the shipped page storage
php artisan storage:link # if the builder uploads media to the public disk
Publish config, the builder view, and the block views. Publish once and commit the published files — you will be editing them.
Where to look first
config/filabuilder.php (or equivalent) — the block registry. This array drives what appears in the block menu, usually in order.src/Blocks/ — HeroBlock, TextBlock, CtaBlock. Read the base block class first: it defines the contract (key, label, icon, validation rules, render view). Everything you extend later hangs off this.resources/views/vendor/filabuilder/builder.blade.php — the canvas view. This is where the FontAwesome 6.7.2 CDN <link> lives as of v1.0.12, and where icon markup is emitted. It is also the file you override when you need to change assets or CSP behaviour.First use case — the 30-minute path
pages table with title, slug, blocks (JSON), published_at.PageResource form so editors compose the page in the admin.[
{ "type": "hero", "data": { "heading": "Welcome", "image": "..." } },
{ "type": "text", "data": { "body": "<p>...</p>" } },
{ "type": "cta", "data": { "label": "Get started", "url": "/signup" } }
]
type to a block class, and includes the block's view:@foreach ($page->blocks as $block)
<x-dynamic-component :component="$resolver->view($block['type'])" :data="$block['data']" />
@endforeach
If the block menu shows real icons instead of blank squares, your install is clean. If not, jump to Gotchas before writing another line.
Treat the config registry as UI, not as code. Adding a block class to the config array is the supported extension point. Order in that array is the menu order — editors notice, so keep it deliberate. Never edit vendor views to reorder blocks.
Model the page payload as JSON, render it as HTML. Store the block array in a JSON column with a array/custom cast. Keep two representations if you can afford it: JSON for re-editing in the builder, compiled HTML for the front end. Re-rendering from JSON on every request is fine for low-traffic pages but couples your front end to the builder's block classes forever — a stored HTML snapshot lets you refactor blocks without breaking published pages.
The render resolver is the piece you own. Build one small service that maps type → block class → view, and wrap it in a fallback:
public function view(string $type): string
{
return $this->blocks[$type]['view'] ?? 'filabuilder::blocks.unknown';
}
An unknown or removed block type must degrade to a visible-but-harmless placeholder, not a 500. Pages outlive block classes.
Custom blocks — extend, don't fork. Subclass the package base block, then define the key, label, render view, validation rules, and icon. v1.0.12 moved icons to FontAwesome markup, so the icon method should return a class string, not an SVG:
public function icon(): string
{
return 'fa-solid fa-quote-left';
}
Return both the style class and the name. fa-quote-left alone renders nothing in FontAwesome 6. If your base class exposes icon()/thumbnail(), override that single method and nothing else.
Validate on the server with the block's own rules. The builder UI is not a security boundary. Run each block's validation rules on save and wrap the whole write in a transaction. A block payload that fails validation should reject the save, not silently store.
One icon source of truth. Because icons are now CSS classes on the block class, your page index, block picker sidebar, and any custom block listing can all read the same value:
<i class="{{ $block->icon() }} mr-2" aria-hidden="true"></i>
<span>{{ $block->label() }}</span>
This is the biggest quiet win of the icon change — you stop duplicating thumbnail assets per surface.
Filament integration tips
blocks JSON keyed by locale — pick one and stay consistent, because the builder edits a single flat canvas.->disabled() / read-only states for non-editors rather than hiding the field, so reviewers can still see what was composed.Testing patterns that survive upgrades
assertSee on final block view output, not on builder internals.data-* attribute on the menu item, never on the icon node.Published views go stale — this is the #1 support ticket after any upgrade. Once you publish builder.blade.php, composer update will not touch it. Post-v1.0.12 the symptom is exactly the thing the release fixed: blank or SVG thumbnails. Re-publish with --force after reviewing the diff, or manually patch the FontAwesome link and icon markup into your published copy. Then php artisan view:clear locally and php artisan view:cache in production.
The FontAwesome CDN is now a runtime dependency of your admin UI. v1.0.12 loads 6.7.2 from a CDN inside the builder view. In air-gapped, intranet, or strict-CSP environments, icons silently render as blank squares — there is no error, no exception, just missing icons. Ensure your CSP allows the CDN for style-src and font-src; FontAwesome pulls webfonts from a separate origin path, so allowlisting only style-src produces a half-working state. If any of this matters, self-host the CSS and webfonts, publish the builder view, and repoint the <link> there. Do not fork the package for this.
Leave the version pin alone. The URL is pinned to 6.7.2. Don't "helpfully" change it to @latest — FontAwesome 6 renamed a stack of FA5 icons, and a major bump will blank your menu again with no obvious cause.
Verify icon names against 6.7.2 specifically. If you copy an icon name from an FA5 cheatsheet, it may not exist. The shipped mapping is HeroBlock → fa-newspaper, TextBlock → fa-paragraph, CtaBlock → fa-bullhorn. Use those as your sanity check.
A custom block with no icon shows an empty slot. There is no meaningful fallback. Always set one explicitly.
Sanitize what the builder saves. GrapesJS produces HTML, and HTML from an editor is untrusted input. Run stored block bodies through a sanitizer (HTMLPurifier or strip_tags with an allowlist) before rendering, and be careful with blocks that accept URLs — validate schemes so javascript: never lands in a CTA href.
Selectors and tests break on the icon swap. Anything targeting the old SVG thumbnail markup — custom CSS, JS in your admin theme, HTML snapshot tests — will break. Repoint selectors at a stable wrapper class or data-* attribute on the menu item, not the <i> node.
Accessibility is a one-line fix you should make now. These icons are decorative. Confirm the builder markup marks them aria-hidden="true" and that the block name is still real text. If your published view predates this, add it.
Uploads need a disk and a symlink. If blocks accept images, point the builder's upload config at a specific disk, run storage:link, and think about what happens when an editor deletes an image that a published page still references — store the path, handle the 404 in the block view.
Debugging blank icons, in order:
fa-solid (style) and the icon name?Upgrade risk is low. v1.0.12 is cosmetic — no API, schema, or config changes called out. Realistic failure modes are stale published views and CSP/CDN blocking, and both present as "icons disappeared" rather than as errors, which is why the checklist above saves more time than reading a stack trace that doesn't exist.
How can I help you explore Laravel packages today?