Laravel Mermaid Laravel Package

Getting Started

Laravel Mermaid 2 targets PHP 8.2+ and Laravel 12 or 13 — verify both before anything else, since this is a hard gate and the main reason an existing install would fail to upgrade.

1. Install the package with Composer (use the exact package name from the README) on a Laravel 12/13 app running PHP 8.2–8.5.
2. Publish the package's config (and assets/views if you plan to customize) with php artisan vendor:publish, then clear caches: php artisan config:clear && php artisan view:clear.
3. Confirm the bundled Mermaid 11 browser integration is being served — this release moves the frontend from the older Mermaid line, so any locally pinned/overridden Mermaid copy should be removed in favour of the bundled one.

Where to look first: the published config file (rendering mode, strictness, theme), then the Eloquent relationship diagram support and the Blade integration point you'll actually use day to day.

First use case: a dev-only "schema" route that renders an Eloquent relationship diagram (ER diagram) generated from your models. Put it behind app()->isLocal() or an authorization gate from the start — see Gotchas.

Implementation Patterns

Dev-only documentation route. Register the diagram route only in local/staging, or gate it with a policy. The most common pattern is a small controller that returns a view containing one diagram, plus a nav link in your local debug toolbar or an admin-only page.

Eloquent relationship diagrams as generated artifacts. Rather than rendering on every request, generate the Mermaid source in a console command or queued job and cache/commit the output. Model reflection is the expensive part; the browser-side render is not. This also lets you diff schema changes in review.

Multiple diagrams per page. v2 explicitly supports several diagrams on one page. Give each diagram its own container with a unique ID and initialize them independently — reusing IDs is the most common cause of "only the first one renders."

Strict rendering in CI. Turn on strict rendering for tests and CI so malformed Mermaid syntax fails loudly instead of silently producing a blank box. Pair this with a test that asserts each generated diagram parses, which is the cheapest regression net for schema diagrams.

Livewire 4 navigation. Under wire:navigate/Livewire 4 SPA navigation, the page isn't fully reloaded, so DOMContentLoaded-based initialization won't fire on subsequent visits. Hook diagram initialization into the livewire:navigated event (or the equivalent Livewire lifecycle hook) so diagrams re-render after navigation.

Theming and customization. Drive appearance from config rather than inline overrides; override the published views only for layout concerns. Keeping diagram definitions in PHP/config and styling in config makes theme changes a one-line diff.

Static output for docs. If you're publishing architecture docs, render to SVG once and commit it. It keeps Mermaid out of production entirely and gives you stable, reviewable artifacts.

Gotchas and Tips

• Mermaid 11 syntax is not a drop-in for older diagram code. Any hand-written or copied diagrams from earlier versions may parse differently or fail. Re-validate every existing diagram after upgrading, especially edge labels and node text containing special characters.
• Strict mode will break things that previously "worked." Diagrams that rendered as empty containers will now surface errors. That's the point — but budget time for the cleanup rather than enabling it in the same deploy.
• Livewire navigation is the top runtime pitfall. If diagrams disappear after clicking a Livewire link, it's almost always missing re-initialization, not a rendering bug. Check the navigation event hook first before debugging Mermaid itself.
• Asset staleness after upgrade. Re-publish assets and clear compiled views; a cached old bundle is a frequent false alarm when the new Mermaid version "doesn't work."
• Don't ship ER diagrams to production. They expose table names, columns, and relationships. Gate the route and exclude generated diagram artifacts from public builds.
• Sanitize any user-supplied label text. Mermaid labels end up in the DOM; treat model/table names from untrusted sources as you would any other rendered string.
• Split large schemas. Rendering is client-side, so a 100-table ER diagram will feel broken regardless of the package. Generate per-domain diagrams instead of one global one.
• Config arrays are typed strictly. With PHPStan level 8 in the package's own CI, config keys are well-defined — prefer published config over ad-hoc runtime overrides, and read the config file rather than guessing key names.
• Extension points: published config (rendering/strictness/theme), published views (layout), and generating diagram source yourself instead of relying on auto-discovery. If auto-generated relationships miss something, generate the Mermaid string manually and pass it in — that escape hatch covers most edge cases without forking.
• Upgrade path: this is a major version. Do it as its own change: bump PHP/Laravel constraints, re-publish config and assets, fix Mermaid 11 syntax, then enable strict rendering.