Lumki Laravel Package

Getting Started

Lumki is a Jetstream add-on, not a standalone admin panel. Before installing, confirm you are on the exact stack it targets: Laravel 8 + Jetstream (Livewire stack, not Inertia) + spatie/laravel-permission + lab404/laravel-impersonate. If any of those are missing, set them up first — Lumki assumes they exist and will fail at runtime if the underlying service providers or migrations are absent.

Minimal steps:

1. composer require kineticamobile/lumki (and spatie/laravel-permission, lab404/laravel-impersonate if not already present).
2. Publish and run the permission migrations, then Lumki's migrations: php artisan vendor:publish --provider="Kineticamobile\Lumki\LumkiServiceProvider" followed by php artisan migrate.
3. Run the package seeder to create baseline roles/permissions, and assign yourself an admin role.
4. Register the package's routes (auto-discovered in most cases) and visit the users route as an admin.

Where to look first:

• Routes file in the package (routes/web.php / a route group behind auth + a role or permission middleware) — understand the URI prefix and middleware before you expose it.
• The migrations — they usually touch the users table (adding fields) and seed roles. Check for column collisions with your existing schema.
• The config file (if published) — role names, guard, and route prefix typically live here.
• The service provider — this tells you what's published, what's auto-registered, and which views are namespaced.

First useful use case: an internal "team admin" screen where a non-engineering admin can list users, assign spatie roles, and impersonate a user to reproduce a support ticket — without writing a CRUD module yourself.

Implementation Patterns

Role seeding as the entry point. Most day-to-day usage starts with defining your role vocabulary (e.g., admin, manager, support, user) in a seeder, then letting Lumki's UI assign them. Keep this seeder idempotent (firstOrCreate on Role) so it can be safely re-run in CI and on fresh environments.

Gate the routes explicitly. Don't rely on the package's default middleware alone. Wrap its route group with role:admin or a can:manage-users permission so that the management surface can't drift from your authorization model. This is the single most important integration point.

Impersonation as a support workflow. Lab404's impersonation is the standout feature: an admin clicks "login as" on a user, the session switches identity, and a "stop impersonating" affordance returns them. Wire the impersonate middleware into your support-facing routes and make sure the return redirect goes back to the admin screen, not the impersonated user's dashboard.

Publishing views for customization. Treat the package views as a scaffold. Publish them, then extend or override — the base tables and forms are generic, and you will want your own branding, extra columns, and filter controls. Publish once and commit the published views; don't re-publish on every deploy or you'll lose edits.

Extending the user table. If you need profile fields beyond what Lumki ships, add them in your own migration after Lumki's migration runs, and add the corresponding fields to the published create/edit views. Keep the User model's $fillable in sync — the package will not know about your columns.

Team scoping. On Jetstream Teams, users belong to a current team. Lumki's default list is often global; if you want per-team management, scope the queries in a small custom controller or Livewire component that wraps the package's views rather than editing the vendor code.

Gotchas and Tips

Version pinning is the headline risk. This package targets Laravel 8 and a Jetstream era that predates Laravel 9+ conventions. It does not "just install" on modern Laravel. Treat adoption as either (a) a greenfield Laravel 8 app, or (b) a port project where you lift the pattern rather than the dependency.

Livewire stack only. Jetstream ships Livewire and Inertia variants; Lumki is built against the Livewire one. Mixing in the Inertia stack will produce missing-view errors that look like broken routes.

Guard mismatch on roles/permissions. Spatie defaults to the web guard. If your app also issues Sanctum tokens or has a second guard, permissions assigned in the UI may not resolve in API contexts. Check config/permission.php and keep guard_name consistent everywhere.

Permission cache. After assigning roles in the UI, the spatie permission cache can hold stale results. If the UI "works" but authorization checks still deny, php artisan permission:cache-reset (or clearing the cache) is the first thing to try.

Migration ordering. Lumki's migrations assume spatie's tables exist. Publish and run spatie's migrations first; otherwise the role-assignment table creation fails with an obscure foreign-key error.

Impersonation in tests. actingAs() bypasses impersonation entirely. If you need to test the flow, drive it through the actual route and assert on the Lab404 session keys rather than calling Auth::login().

License is NOASSERTION. Before shipping in a commercial product, read the actual LICENSE file in the repo — the classifier could not identify a standard license, which means the terms are bespoke and need human review.

Abandonment signal. With a modest star count and a fixed Laravel 8 target, expect to vendor or fork. Budget for maintenance: keep the published views and any custom controllers in your own repo so a composer update can't silently change your admin UI.