Laradminlte Laravel Package

Getting Started

• Pin the beta before adopting it. LaradminLTE v1.0.0-beta4 bundles AdminLTE v4.9.1 and changes asset/config defaults, so treat upgrades as deliberate and test them in a branch.
• Publish and review the package config first. The important day-to-day switches now include authentication scaffolding, Fortify route management, AdminLTE color palette selection, sidebar search behavior, avatar mode, and Livewire SPA/Vite integration.
• Re-publish assets and config when coming from beta3. The release explicitly warns that AdminLTE v4 assets and configuration files changed. Follow the package updating guide rather than relying on a Composer update alone.
• First practical use case: scaffold an admin area, enable the package auth scaffolding only if you want it, choose a palette, enable sidebar search, and set the default avatar mode to local_initials if you want local SVG initials instead of an external avatar service.
• Where to look first: the package config, the updating/getting-started docs, the Livewire SPA navigation docs, the Vite examples, and the sidebar search configuration docs. For Livewire SPA apps, read the AdminLTE initialization notes before adding custom JavaScript.

Implementation Patterns

• Use config-first customization. Palette, sidebar search, avatar defaults, auth scaffolding, and Fortify route handling should be driven through the published config and environment overrides. Keep a clear project-level config diff so upgrades are easier to review.
• Enable auth scaffolding explicitly. Since beta4 disables authentication scaffolding by default, applications that depend on the package’s auth screens must opt in through configuration. Document that decision in the project README.
• Let Fortify own routes when needed. If the application already defines Fortify routes, disable LaradminLTE’s Fortify route management to avoid duplicate or conflicting route registration. Check php artisan route:list after changing this.
• Use local_initials for low-friction avatars. The new local SVG initials service is useful for internal admin apps, privacy-sensitive projects, and environments without external avatar services. Set it as the default mode and verify how existing users fall back.
• Adopt Livewire SPA navigation carefully. The package now supports Livewire SPA navigation better, but custom scripts must follow the updated AdminLTE initialization lifecycle. Avoid manually creating AdminLTE instances on every Livewire body swap; rely on the package lifecycle where possible or guard against re-initialization.
• Use the documented wire:navigate opt-out for exceptional links. Most internal navigation can stay SPA-like, but links that need a full reload—logout, file downloads, third-party redirects, or pages with conflicting JS—should disable wire:navigate per link.
• Wire AdminLTE assets through Vite. Use the package’s updated Vite initialization examples for app builds, and verify both dev server and production build behavior. This is especially important if you customize the layout or add AdminLTE JS components.
• Treat sidebar search as a configuration feature, not a custom widget. Enable it through config, publish the updated assets, and test it against the project’s menu structure rather than forking the widget immediately.
• Day-to-day workflow: build admin screens with Blade/Livewire, keep menu/layout configuration in project config, use Vite for frontend assets, and maintain an upgrade checklist covering config re-publish, asset re-publish, auth/Fortify settings, and Livewire SPA smoke tests.

Gotchas and Tips

• Auth scaffolding is now off by default. This is the most likely upgrade surprise. If login/register/password-reset screens disappear after upgrading, check the auth scaffolding config before debugging routes or middleware.
• Updating from beta3 requires more than composer update. Re-publish the AdminLTE v4 assets and configuration files, then compare the published config with the previous version so intentional local changes are preserved.
• Livewire SPA + AdminLTE can create duplicate instances. The release warns that the previous initialization approach may create multiple AdminLTE instances after SPA navigations. Audit custom JS for direct AdminLTE initialization and move it to the updated lifecycle.
• Disable wire:navigate selectively. Do not globally disable SPA navigation just to fix one problematic link. Use the documented per-link opt-out and keep the rest of the admin experience SPA-like.
• Fortify route conflicts are configuration problems, not package bugs. If routes are duplicated or missing, check whether LaradminLTE route management and the application’s own Fortify routes are both active.
• Clear caches after config changes. Run php artisan config:clear or rebuild config cache after toggling scaffolding, Fortify route management, palette, sidebar search, or avatar mode.
• Missing palettes or sidebar search usually point to assets. Confirm the updated AdminLTE CSS/JS assets were published and included, and that the app is using the expected Vite entry points.
• Check Vite in both dev and production. The release changes initialization scripts and documentation. A layout that works under npm run dev can still fail in a production build if the manifest or entry points are stale.
• Keep beta upgrade testing focused. Smoke-test authentication, Fortify routes, Livewire SPA navigation, sidebar search, avatars, JS components, and Vite builds. Use browser console logs to catch AdminLTE lifecycle errors, and verify only one AdminLTE instance is active after navigation.
• Extension point to watch: the local initials avatar service is a clean place to standardize avatar rendering. If the project needs different avatar behavior, wrap or override the configured mode at the application layer rather than scattering avatar logic across views.