🚀 Filament Headless (shabeer-dev/filament-headless)

A modular, turnkey toolkit and CLI generator for building high-performance, multilingual websites using Filament v5 as a Headless CMS and Inertia.js v3 + React 19 as the decoupled frontend, fully aligned with Laravel Boost MCP & Guidelines.

🏛️ Architecture Overview

┌────────────────────────────────────────────────────────────────────────┐
│                         Filament v5 Admin Panel                        │
│   • Singleton Resources (No Table Views; direct-to-edit for ID 1)      │
│   • Pure Modular Block Builder (Drag, drop, and reorder sections)     │
│   • Spatie Translatable + Happenv (In-place Tabbed Locale Switcher)    │
│   • Real-Time Google SERP & OpenGraph Social Card Live Previews        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Saves JSON & Media
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                 Laravel 13 Content Engine & Caching                    │
│   • SerializesLocalizedStrings Trait (Flattens JSON into active locale)│
│   • ContentObserver: Automatically purges cache across all locales     │
│   • ContentPageController: Cache::rememberForever with locale keys     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Hydrates Inertia Payload
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   Inertia.js v3 + React 19 Frontend                    │
│   • AppLayout: RTL / LTR dynamic direction based on active locale      │
│   • BlockRenderer: Dynamic section dispatcher (<BlockRenderer />)     │
│   • Laravel Wayfinder: Type-safe route functions (@/routes, @/actions) │
└────────────────────────────────────────────────────────────────────────┘

⚡ Key Highlights

• Singleton Page Pattern: Eliminates confusing data tables for website pages (Home, About, Services, etc.). Clicking a page navigates directly to its singular edit form.
• Pure Modular Block Builder: Construct dynamic pages where admins can add, reorder, and remove blocks freely using Filament's Builder component. Rendered on the frontend via a dynamic React <BlockRenderer />.
• Laravel Boost MCP & Skill Integration:
  • Automatically synchronizes with boost.json (filament/filament, spatie/laravel-medialibrary, spatie/laravel-translatable).
  • Registers the headless-architecture skill in boost.json and .agents/skills/.
  • Harmonizes guidelines in GEMINI.md and AGENTS.md so Boost-aware LLMs respect the architecture.
• Pest 4 Feature Test Generation: php artisan headless:make-page automatically scaffolds feature tests (tests/Feature/Pages/{Name}PageTest.php) asserting localized 200 HTTP responses, Inertia component rendering, and cache invalidation in accordance with Boost testing rules.
• Interactive Prompts Installer: Powered by Laravel\Prompts for an interactive CLI setup wizard (language multi-selection, default locale, starter pages).
• System Diagnostics Doctor: php artisan headless:doctor validates PHP extensions, public storage symlinks, Spatie media tables, Wayfinder routes, Boost sync, and Pest configuration.
• Configurable Multi-Language Engine: Centralized in config/headless-kit.php. Add or remove languages without touching PHP or React code.
• Dynamic RTL / LTR Support: Automatically detects right-to-left languages (Arabic, Hebrew, Farsi, Urdu) and adjusts layout direction.
• Real-Time SERP & Social Previews: Live Google search snippet and Twitter/Facebook OpenGraph card simulation directly inside the Filament admin form with live character count analysis.
• Architecture Linter: php artisan headless:lint audits content models, Filament resources, and React pages to enforce architectural purity and catch drift.
• AI Agent Context Generator: php artisan headless:agent-context compiles a real-time Markdown ground-truth digest (.agents/headless-context.md) for LLM agents.
• One-Command Scaffolding: php artisan headless:make-page {Name} scaffolds all 7 layers of a page in seconds.

📋 Requirements

📦 Installation in Any Laravel Project

Install the package via Composer:

composer require shabeer-dev/filament-headless

Then run the interactive installer:

php artisan headless:install

The installer will prompt you to:

1. Select supported languages (English, Arabic, Spanish, French, German, Chinese, etc.).
2. Pick your default application language.
3. Select starter pages to scaffold immediately (Home, About, Services, Contact).
4. Automatically synchronize with boost.json and inject guidelines into GEMINI.md / AGENTS.md.

🛠️ CLI Commands & Generators

🧱 Pure Modular Block Builder

Backend (Filament)

Allow editors to freely compose and re-order content using BlockCatalog::all():

use App\Filament\Blocks\BlockCatalog;
use Filament\Forms\Components\Builder;

Builder::make('blocks')
    ->label('Page Sections')
    ->blocks(BlockCatalog::all())
    ->collapsible()
    ->cloneable()

Built-in blocks include:

• hero: Title, highlighted text, badge, dual CTAs, background media.
• stats: Counter metrics band with target numbers and suffixes.
• bento_grid: Responsive multi-span feature cards with icons and badges.
• overview: Split 2-column text and media layout.
• faq: Collapsible questions and answers.
• cta: Full-width banner with target action.

Frontend (React)

Render any list of dynamic blocks with one line:

import BlockRenderer from '@/components/blocks/BlockRenderer';

export default function ServicesPage({ content }) {
    return <BlockRenderer blocks={content.blocks} />;
}

🌐 Multi-Language Configuration (config/headless-kit.php)

All supported languages, their native names, flags, and text directions are configured in a single place:

// config/headless-kit.php
return [
    'locales' => [
        'en' => [
            'name' => 'English',
            'native' => 'English',
            'dir' => 'ltr',
            'flag' => 'US',
        ],
        'ar' => [
            'name' => 'Arabic',
            'native' => 'العربية',
            'dir' => 'rtl',
            'flag' => 'AE',
        ],
        'es' => [
            'name' => 'Spanish',
            'native' => 'Español',
            'dir' => 'ltr',
            'flag' => 'ES',
        ],
    ],

    'default_locale' => env('APP_LOCALE', 'en'),
    'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),
];

🧪 Pest Feature Testing (Boost Standard)

Every page generated with php artisan headless:make-page comes with a ready-to-run Pest 4 feature test:

// tests/Feature/Pages/ServicesPageTest.php
use Inertia\Testing\AssertableInertia as Assert;

it('renders the services page successfully for default locale', function () {
    $response = $this->get('/en/services');

    $response->assertStatus(200);
    $response->assertInertia(fn (Assert $page) => $page
        ->component('Services')
        ->has('content')
    );
});

Run tests with:

php artisan test --compact

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Format with Pint (vendor/bin/pint)
4. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

📄 License

The MIT License (MIT). Please see License File for more information.