Blatui Admin Laravel Package

Getting Started

• Install into an existing Laravel app with Composer. The package is now at v0.6.0 but still pre-1.0, so pin the minor explicitly and expect churn:

  composer require x-multibyte/blatui-admin:^0.6.0
  

• Run the package installer. The release notes confirm the command name:

  php artisan blatui:admin
  

  Run it under version control so the diff of every scaffolded/published file is visible. It installs Livewire by default and will also detect laravel/boost if present.
• If you use Laravel Boost, the installer will prompt you to sync the package's AI context. Do that immediately after install:

  php artisan boost:update --discover
  

  This makes the package's core guidelines and the blatui-admin-development skill available to your AI tooling, which is genuinely useful for day-to-day component work in this package.
• First places to look after install:
  • config/blatui-admin.php or similarly named published config
  • routes/ for admin routes added by the package
  • resources/views/vendor/blatui-admin/ after publishing views
  • src/Livewire/ or app/Livewire/ for the Livewire components the package expects you to extend
  • vendor/x-multibyte/blatui-admin/resources/boost/guidelines/core.blade.php and .../skills/blatui-admin-development/SKILL.md for the package's own guidance on extending it
• First use case: install into a fresh or disposable Laravel app, confirm the admin dashboard/auth area loads, run boost:update --discover if you use Boost, then add one simple CRUD screen using the package's Livewire and Blade conventions. Do not start with a complex resource until the install pipeline is verified in your environment.

Implementation Patterns

• Treat BlatUI Admin as an admin-panel foundation, not a black box. Publish the config, views, and assets you need, then extend the published files rather than editing vendor code.
• Lean on Livewire for day-to-day screens: tables, filters, forms, modals, and CRUD actions should be Livewire components using the package layout and Blade components.
• If you use an AI assistant (Boost, or any tooling that reads repo context), point it at the shipped Boost assets before generating screens. The blatui-admin-development skill encodes the package's conventions, which beats letting the model invent patterns from scratch. Re-run discovery after upgrading the package:

  php artisan boost:update --discover
  

• Register admin routes in a dedicated route group with prefix, name, and middleware:

  Route::prefix('admin')
      ->name('admin.')
      ->middleware(['web', 'auth'])
      ->group(base_path('routes/admin.php'));
  

• Keep authorization explicit. Use Laravel policies/gates for resource actions and consider a separate admin guard if your app has non-admin users. The installer scaffolding is not a substitute for authorization.
• If the package exposes resource registration or navigation config, use it instead of hand-writing menus. Keep navigation entries in config so day-to-day additions do not require touching package internals.
• For styling, BlatUI implies Tailwind. Ensure your tailwind.config.js content paths include published package views and Livewire component views, then rebuild assets after publishing:

  npm run build
  

• Make the installer repeatable. In CI or onboarding docs, capture the full sequence: Composer install, php artisan blatui:admin, asset publishing, migrations, frontend build, and (optionally) php artisan boost:update --discover. This matters more than usual pre-1.0 because the setup pipeline is still evolving.
• Day-to-day workflow: create a Livewire component for the screen, use the package layout, add the route and navigation entry, protect it with middleware/policy, and validate with a feature test.

Gotchas and Tips

• Still pre-1.0 despite the version number looking mature. Pin the version in composer.json, review changelogs before updating, and expect breaking changes in config keys, install commands, or component APIs. The jump from 0.0.1 to 0.6.x in a handful of releases is a signal, not a guarantee of stability.
• Verify Laravel, PHP, and Livewire version compatibility from the package composer.json. Release notes do not state supported versions, so do not assume your app's versions are supported.
• Boost integration only activates when laravel/boost is installed in the host app. The installer's detection prompt will not appear otherwise — that's expected, not a broken install.
• php artisan boost:update --discover will fail if Boost isn't installed. Don't put it unconditionally in CI scripts.
• The v0.6.0 .gitattributes change removes export-ignore for /resources/boost so Composer dist installs bundle the AI context assets. If you install via a VCS/path repository, or you're on an older tag, confirm vendor/x-multibyte/blatui-admin/resources/boost/ actually exists before relying on the guidelines or skill files.
• Boost guidelines shipped in the package are advisory context, not enforced rules. They will not stop you from writing code that contradicts the package's conventions — review generated components rather than accepting them blindly.
• If styles or scripts are missing, check the asset publish tag and Tailwind content globs. Typical fixes are republishing assets, clearing caches, and rebuilding frontend assets:

  php artisan vendor:publish --tag=blatui-admin-assets
  php artisan optimize:clear
  npm run build
  

• Debug with Laravel's normal tools first: php artisan route:list, php artisan about, logs, and php artisan vendor:publish --list to discover available publish tags. Confirm which config file the package actually reads after installation.
• Avoid editing vendor files. Use published views/config and, where supported, extend or override Livewire components through class extension or container bindings.
• Check that admin routes are actually protected. Default scaffolding can leave routes reachable if middleware is misconfigured. Test with an unauthenticated request.
• Documentation is still on the thin side, though the Boost guidelines/skill and the ADRs under docs/decisions/ are now a reasonable starting point for understanding intent. Timebox a small spike before committing to it for a production admin panel.