Laravel Mermaid Laravel Package

Product Decisions This Supports

• Feature viability for in-app diagramming. This package turns Mermaid diagrams into a first-class Laravel concern — Blade rendering, configuration, strict rendering modes, and multiple diagrams per page — so "let's show the data model in the admin panel" becomes a small scoped ticket rather than a frontend project.
• Build vs. buy. The bundled browser integration, Mermaid 11 assets, and Livewire 4 navigation handling are exactly the glue work teams underestimate. Buying (adopting) here avoids owning a JS bundling pipeline, asset publishing, and SPA-navigation re-render logic.
• Living documentation as a roadmap item. Auto-generated Eloquent relationship diagrams mean schema docs can be derived from models instead of hand-maintained. This supports decisions like "invest in onboarding docs" or "expose an internal ERD page" at near-zero incremental cost.
• Framework upgrade planning. Declared support for Laravel 12 and 13 with CI across PHP 8.2–8.5 makes this a safe dependency to carry through the next upgrade cycle — a positive signal when triaging packages that block platform upgrades.
• Scoping use cases honestly. This is a rendering/integration layer, not a diagram editor. It fits internal tooling, developer onboarding, admin-panel ERDs, and architecture docs; it does not cover collaborative editing, persisted user-authored diagrams, or customer-facing visualization products.
• Risk budgeting. "Community-supported" plus a 7-test / 19-assertion suite means treat it as a convenience dependency, not load-bearing infrastructure. Keep it behind an internal-only surface and avoid coupling core product flows to it.

When to Consider This Package

Adopt when:

• You are on Laravel 12 or 13 and PHP 8.2+ — v2.0.0 hard-requires both, so older stacks must stay on a prior major.
• You want Mermaid rendering without hand-rolling Mermaid 11 asset bundling, config publishing, and strict-mode rendering.
• Eloquent relationship diagrams are on your list — auto-deriving an ERD from models is the differentiating capability here.
• You use Livewire (v4 navigation is explicitly covered) or other SPA-style navigation where diagram re-initialization is a known failure mode.
• The audience is internal: engineers, onboarding docs, admin back office.

Look elsewhere when:

• You are pinned to Laravel 10/11 or PHP < 8.2 — upgrading the platform is the prerequisite, not the package.
• You need a diagram editor (create/edit/persist diagrams by end users), collaborative editing, or versioned diagram storage.
• You need non-Mermaid rendering (Graphviz, D3, Excalidraw) or server-side SVG generation for PDFs/emails — the bundled browser integration implies client-side rendering.
• You have hard constraints on runtime JavaScript or a strict CSP that treats bundled frontend assets as a blocker.
• You require a vendor SLA, security response commitments, or deep test coverage as an adoption gate — the published validation (7 tests / 19 assertions plus demo-based browser checks) is thin for anything customer-facing.
• Your use case is customer-facing analytics visualization; a rendering helper for docs is the wrong tool for a product surface.

How to Pitch It (Stakeholders)

For executives: A small, low-cost dependency that lets us generate and display architecture and database diagrams directly inside our internal Laravel tools. It keeps documentation aligned with the actual code instead of drifting, and v2.0.0 is explicitly built for the Laravel 12/13 and PHP 8.2–8.5 range we are standardizing on — so it will not become an upgrade blocker. Cost is a composer dependency; the tradeoff is that it is community-supported rather than vendor-backed, so we would scope it to internal tooling rather than customer-facing surfaces.

For engineering: Drop-in Laravel integration for Mermaid 11 with strict rendering, multi-diagram pages, Eloquent relationship diagram generation, and Livewire 4 navigation handling — the exact plumbing we would otherwise build and maintain. Quality signals are mixed but net positive: PHPStan level 8, Pint, CI across PHP 8.2–8.5, dependency audits, frontend builds, and real-browser SVG plus Livewire interaction coverage in the Laravel 13 demo. The caveat is test depth — 7 tests / 19 assertions — so plan to validate our specific diagram shapes in a spike before committing, and keep it isolated behind an internal-only route.

Ask: Approve a timeboxed spike on an internal admin page to confirm rendering under our CSP and Livewire setup before adding it to the dependency baseline.