Blatui Laravel Package

Technical Evaluation

Architecture fit. BlatUI is a source-distribution library, not a runtime dependency. The CLI copies Blade components into resources/views/components/ui/ and the theme/JS engine into resources/css and resources/js. That inverts the usual vendor-ownership model: after install, we own ~155 components and every line of their Alpine behavior. For a TPM this is the single most important property of the package. It buys unlimited customization, no vendor lock-in at runtime, no upgrade-forced-breaking-change treadmill, and trivially auditable markup — which matters if we have code-review, accessibility, or design-system governance requirements. It costs us the thing a vendor normally absorbs: patch delivery, security triage, and drift management.

The package is well-scoped for the Laravel/Blade idiom. Pure Blade + Alpine + Tailwind is the lowest-friction stack for a server-rendered Laravel app; there is no Node build step beyond Vite, no React island, no hydration story to reason about. The blatui:add dependency resolver (transitive component deps, plus printing required Composer/npm peers) and blatui:doctor (typeless buttons in forms, leaked tags) are the kind of affordances that signal the author has actually shipped this into apps rather than just authored a component gallery. The 1.24.1 changelog is a useful tell: a real CSS-vs-JS breakpoint bug, fixed with both a render test and a browser test that fails on the pre-fix component. That is a maintainer operating with a regression discipline.

Integration feasibility. Feasible in a day for a greenfield Laravel 11/12/13 app on Tailwind v4 + Alpine 3. The install path is explicit and the doc is unusually careful about the two genuine footguns: (1) double-booting Alpine by importing blatui.js when the app already runs Alpine, and (2) the Livewire/Flux case where Livewire owns Alpine and we must register via alpine:init and install plugins only. blatui:init as a doctor command gives a cheap, verifiable checkpoint before we write any UI.

The constraint that gates everything is Tailwind CSS v4. BlatUI relies on v4-only features (@theme inline, oklch tokens). Any existing app on Tailwind v3 must run npx @tailwindcss/upgrade first, and that migration is a project in its own right — it can restyle arbitrary existing pages and is not something we should bundle into "adopt a component library." Where we are on v4 already, or greenfield, integration cost collapses.

Technical risk.

Key questions for the maintainer / for us.

1. Can you confirm and normalize the license to MIT in the repo metadata (or clarify the NOASSERTION)?
2. What is the security disclosure policy and expected turnaround for a component-level flaw? Is there a mailing list or GitHub Security Advisory path we can subscribe to?
3. What is the intended support window across Laravel 11 → 13 and Tailwind v4 → v5? Which point releases are safe to sit on?
4. Are the registry endpoints (/r/blocks/*, /r/charts/*) versioned and immutable, or does fetching the same URL a month apart yield different code?
5. Does the blatui:mcp server have any write path beyond reading the registry and invoking blatui:add? What should we restrict in agent-driven environments?
6. Is Flux Pro already in use anywhere in our estate? Each such surface is a migration decision, not a drop-in.

Integration Approach

Stack fit. BlatUI targets exactly one stack and does so honestly: PHP 8.2+, Laravel 11/12/13, Tailwind v4, Alpine 3, Node 18+. Peer packages are small and uncontroversial — gehrisandro/tailwind-merge-laravel for class conflict resolution and mallardduck/blade-lucide-icons for icons. Charts add apexcharts (lazy-loaded by the engine), which we can drop if we don't need 70 chart variants. No PHP runtime coupling beyond the service provider; no middleware, no DB, no queue. Blast radius on the backend is effectively zero.

Migration path. Three distinct entry points, each with different cost:

• Greenfield / new Laravel app. Publish foundations, import them from the two Vite entrypoints, run blatui:init, then blatui:add per feature. This is the cheap path and the one I'd recommend as the pilot.
• Existing Tailwind v4 app, already running Alpine. Additive per the doc: @import "./blatui.css" below the Tailwind import, and register via registerBlatUI(Alpine) from blatui-core.js before Alpine.start() — never import blatui.js. Low risk, mechanical.
• Existing Livewire app. Livewire owns Alpine. Install plugin packages only (no alpinejs), register inside the alpine:init hook, and pass { darkMode: false } if Flux already drives dark mode. Correct but easy to get wrong; this is the configuration that needs a documented internal runbook and a code-review checklist item, because the failure mode (silent double-Alpine) is confusing to debug.
• Tailwind v3 app. Blocked until the v4 upgrade lands. Sequence this as two separate workstreams with a gate between them; do not let "adopt BlatUI" become a cover story for an under-scoped Tailwind migration.

Compatibility. Compatibility is mostly the peer-dependency graph plus Vite. The realistic compatibility watch-list is: Tailwind major version, Alpine major version, Livewire's bundled Alpine, and Flux's dark-mode ownership. Everything else is inert. Worth an explicit note that the package is a monorepo where stubs/ is generated from apps/demo/ and CI enforces no drift — which means the published artifacts and the demo site cannot silently diverge, a genuinely good sign for a copy-paste library.

Sequencing. Staged, with explicit exit criteria:

1. Legal + governance (week 1). Resolve license. Decide whether blocks/charts are in scope (if yes, mirror the registry JSON internally; if air-gapped, out of scope). Add blatui:update --dry-run --diff --ignore-whitespace to a recurring calendar item.
2. Pilot (week 1–2). One greenfield or already-v4 surface. Publish foundations, blatui:init green, install 8–12 components covering form, overlay, and data-table patterns. Exit criteria: blatui:doctor clean, axe-core clean on two real pages, one form control verified against wire:model.
3. Design-system lock (week 2–3). Customize the published blatui.css tokens before breadth, because tokens are the cheap global lever and per-component edits are not. Publish an internal rule: token edits yes, component-fork edits require review (they are what makes future updates expensive).
4. Breadth (week 3–6). Feature-by-feature adoption. blatui:add per feature rather than --all — --all maximizes the eventual diff-review surface for zero near-term benefit.
5. Flux displacement (only if applicable, week 6+). Per-surface, driven by cost, not by a mandate.

Operational Impact

Maintenance. This is the dominant cost and it should be budgeted explicitly, not discovered. We own the copied source: no automated security patches, no forced upgrades, and no vendor telling us something broke. In exchange, nothing breaks without our consent. Practically that means (a) a named owner for upstream release review, (b) an update cadence tied to releases we care about rather than every 1.28.x bump, and (c) a discipline of token-level customization over component-level forks, because forks convert every future update into manual conflict resolution. The .bak / --force / --dry-run / --ignore-whitespace tooling is genuinely thoughtful here — it treats "we can't tell your edit from a stale copy" as an honest problem rather than papering over it — but it only helps teams that use it deliberately.

Realistically: expect ~2–4 hours per update cycle for a mid-size surface with light customization, and materially more if the team has forked components. Treat that as a recurring line item.

Support. There is no commercial support. Support is the maintainer's GitHub issue tracker plus the docs site, and with 0 dependents there is no community to fall back on. Two mitigations: (1) because we own the source, worst case we fix it ourselves — this is the real safety net and it is a strong one for UI code; (2) keep our forks minimal so a self-fix is a small patch, not a rewrite. Internal support load concentrates on two areas: Alpine/Livewire bootstrap wiring (well-documented, so a one-page runbook solves it) and the update-diff workflow (process, not technology).

Scaling. Two axes. Team scaling is favorable: Blade components with a stable x-ui.* API are easy to onboard onto, and the component-per-file structure means parallel work doesn't collide. The hazard is uncontrolled forking — twenty engineers, twenty slightly different button.blade.php variants. Enforce the token/component boundary in review. Application scaling is unaffected: these are server-rendered views, no client-side component runtime, no bundle-size catastrophe. The only runtime cost is ApexCharts (lazy-loaded, drop it if unused) and the Alpine plugins. Accessibility at scale is the item to instrument — put axe-core in CI so AA is a gate rather than a claim.

Failure modes. Ranked by likelihood × impact:

• Duplicate Alpine instance — components render but interactions silently no-op. Highest-frequency failure, entirely caused by importing blatui.js alongside an existing Alpine/Livewire app. Mitigate with the runbook and a review checklist item.
• Tailwind v4 assumption violated — tokens and @theme mapping don't resolve; components render unstyled. blatui:init catches this early; the trap is skipping the doctor.
• Dark-mode double-toggle — BlatUI's theme store and Flux both flip .dark, producing theme flicker or stuck state. Fixed by { darkMode: false }; invisible until someone tests a theme toggle.
• Formatter-induced diff noise — every component reads as modified, updates become unreviewable. Mitigate by standardizing on --ignore-whitespace in the update runbook.
• Registry fetch failure or drift — blocks/charts unavailable, or the same URL returns different code later. Mitigate by vendoring fetched block/chart sources into the repo on acquisition; never fetch at build or deploy time.
• Upstream fixes never arriving — the quiet one. A component bug is fixed upstream and our copy silently stays broken because nobody re-ran the diff. Counter with a scheduled --dry-run --diff sweep, monthly at minimum.
• License surprise — the only failure here that can't be fixed with engineering effort after the fact. Resolve first.

Ramp-up. Low, and front-loaded. A Laravel developer productive in Blade is productive with x-ui.* in under a day — the component APIs are deliberately shadcn-shaped, so prior shadcn/ui exposure transfers directly and even prior-less developers get readable markup. The learning curve is not component usage; it is the operational envelope: Alpine ownership in our specific app, the published-foundations model (edit tokens, re-sync with vendor:publish --force, run blatui:init), and the update workflow. Budget one focused session for the team lead on those three, then a written runbook. The skills/blatui-development/SKILL.md agent skill is a genuine accelerant for AI-assisted development — but it also means agents can pull component code (and registry content) into the repo autonomously, which needs a governance answer if blatui:mcp is enabled anywhere.

Verdict from a delivery standpoint: strong technical fit for Laravel/Blade on Tailwind v4, unusually honest tooling, and a favorable ownership model for UI specifically. The two things standing between "evaluate" and "adopt" are not technical — they are the unresolved license and the absence of any adoption signal behind a 262-star, single-maintainer project. Resolve the license, run the two-week pilot, and the decision makes itself on evidence.