Lottie Laravel Package

Getting Started

This release is a packaging rename, not a feature release — so the first thing to do is fix the install line, then read the component class.

# new installs
composer require visualbuilder/filament-lottie:^5.0.0-beta

# existing installs — swap the package, keep the code
composer remove visualbuilder/lottie
composer require visualbuilder/filament-lottie:^5.0.0-beta

Your PHP code does not change. The namespace is still Visualbuilder\Lottie, so use Visualbuilder\Lottie\Components\Lottie; and every existing class reference keep working untouched. Only the Composer package name moved (for consistency with the visualbuilder/filament-* family).

Where to look first, in order:

1. vendor/visualbuilder/filament-lottie/src/Components/Lottie.php — the component's public API is the whole surface area you'll actually use.
2. The package's Blade view and resources/dist — tells you how the animation JSON is loaded and whether assets are published or served from the vendor path.
3. composer.json of the package — check extra.laravel.providers and any publishable config/views before assuming you need to register anything manually.

First use case: render a Lottie animation in a Filament panel — an empty-state illustration on a table, a success animation after a form submit, or an onboarding graphic in a custom page. Point the component at a .json Lottie file and confirm it renders in the panel before wiring it into anything conditional.

Implementation Patterns

Treat the animation file as an application asset, not a package asset. Put your .json files under public/ (or your Vite resources/ pipeline) and pass a stable URL to the component. Referencing files inside vendor/ works locally and breaks on deploy when composer install --no-dev runs.

One component per animation, configured at the call site. Because the class name and namespace are unchanged, the pattern you already have keeps working — this release requires zero refactoring. If you were mid-migration when beta.1 landed, finish it on the new package name and don't touch the use statements.

Pin the whole visualbuilder/filament-* family together. The rename exists specifically so these packages version and resolve as a set. If you use more than one, constrain them to compatible ranges in a single commit so Composer's solver doesn't mix a renamed package with siblings still expecting the old name.

Beta channel discipline. You're on ^5.0.0-beta, which Composer treats as pre-release stability. If your root composer.json sets "minimum-stability": "stable", either add "visualbuilder/filament-lottie": "^5.0.0-beta" with an explicit @beta flag or temporarily allow beta stability — otherwise composer update silently skips the package.

Verify rendering, not installation. After the swap, load a page containing the component and confirm the animation initialises. A successful composer require plus a broken asset path is the failure mode this rename is most likely to surface (because the package path under vendor/ changed from visualbuilder/lottie to visualbuilder/filament-lottie).

Gotchas and Tips

The old package name is gone, but your lockfile may not be. Run composer remove visualbuilder/lottie before requiring the new name, then composer dump-autoload and clear caches. If you only add the new package, you can end up with both in composer.lock, duplicate service providers, and confusing "class already defined" or double-registered asset behaviour.

Anything hardcoding the vendor path breaks. If you have a published view override, a @vite/asset reference, or a CI script that points at vendor/visualbuilder/lottie/..., update it to vendor/visualbuilder/filament-lottie/.... This is the only place the rename can bite you, and it's outside what composer require fixes.

The esbuild bump is dev-only and cannot affect your app. ^0.23 → ^0.25 clears GHSA-67mh-4wv8-2f99 (dev-server CORS leak). The advisory only reaches esbuild's dev server, which this package's shipped build never runs. It matters only if you're building the package's assets from source locally — in which case npm install inside the package now pulls a patched bundler. No action needed on a normal composer require.

Republish assets after upgrading. Because the vendor directory path changed, previously published views/config/assets may be stale or pointing at the old location. Re-run the package's vendor:publish tags (check php artisan vendor:publish --provider="Visualbuilder\Lottie\...") and diff against what you had.

Debugging order when an animation doesn't appear: (1) is the .json URL reachable in the browser and returning valid JSON rather than a 404 HTML page; (2) did the JS runtime actually load — check the network tab for the Lottie player bundle; (3) in a Livewire/Filament context, is the component being re-rendered without re-initialising the player (a classic Alpine/Livewire morph issue) — wrap re-init in a hook rather than relying on first paint.

Extension points worth knowing before you fork. Published Blade views are the intended customisation surface — override markup and player options there rather than subclassing the component, so future betas don't fight your changes. If the component exposes fluent setters for loop/autoplay/speed, use those at the call site and keep the view generic.

Track the beta line actively. 5.0.0-beta.2 is a packaging patch, but betas in a family of filament-* packages tend to precede coordinated 5.x releases. Keep the rename commit isolated so a future breaking beta is a one-line revert rather than an archaeology exercise.