Adminkit Laravel Package

Getting Started

yrizzz/adminkit is a starter kit, not a runtime package — you don't require it into an existing app and call its API. The expected flow is scaffold-then-fork: create a project from the repo, or copy its scaffolding into a fresh Laravel 13 app, then own the code from that point forward.

Minimal path:

1. Clone/scaffold a Laravel 13 app from the repo (or laravel new and pull in the app skeletons + config).
2. composer install && npm install.
3. Copy .env.example to .env, set DB credentials, php artisan key:generate.
4. php artisan migrate --seed — the seeder is where the initial admin user and any roles/permissions live.
5. npm run dev alongside php artisan serve.

Where to look first, in order:

• routes/web.php — the admin route group and middleware stack define the whole access model. Read this before anything else.
• app/Livewire/ (or app/Http/Livewire/) — the dashboard widgets and resource screens are Livewire 4 components; this is where 90% of your day-to-day edits happen.
• resources/views/layouts/ — the shell (sidebar, topbar, dark-mode toggle). Navigation is almost always a data structure fed into this layout, not hardcoded markup.
• resources/css/app.css — Tailwind v4 means theme tokens (@theme, CSS custom properties) live here, not in a tailwind.config.js.
• config/adminkit.php (if published) — brand name, route prefix, middleware, and nav registration typically hang off this.

First real use case: log in with the seeded admin, then build one screen end-to-end — a list + create/edit modal for a single model (e.g. Users). That forces you through the layout, the Livewire component conventions, form validation, and Tailwind theming in one pass, which is the fastest way to learn the kit's opinions.

Implementation Patterns

Treat it as an application skeleton, not a dependency. Commit the scaffold to your repo as day-zero and never plan to composer update it. Cherry-picking upstream fixes means diffing the repo against your tree — so keep your own additions in clearly separated namespaces/directories to make that diff readable.

Livewire component-per-resource for CRUD. The idiomatic pattern is one component holding $this->records, a $form state object, and methods like save(), edit($id), delete($id). If the kit ships with WithPagination + #[Validate] attributes, match that style rather than introducing controllers — mixing a controller-based CRUD into a Livewire admin creates two competing state models.

Form Objects / DTOs over loose public properties. For anything past a 5-field form, put validation and hydration in a dedicated form object. This is what makes the screens testable and keeps the component focused on orchestration.

Navigation as configuration. Extend the admin menu by appending to the nav array/config rather than editing the sidebar Blade. That keeps active-state highlighting, permission filtering, and collapsible groups working for free — and means one place to change when you reorganize.

Authorization at the route group + per-component. The route group middleware handles the coarse "is this an admin" check; add policies (or Gate checks in mount()) for row-level access. Don't rely on hiding nav links — Livewire endpoints are directly callable.

Blade + Alpine for micro-interactions, Livewire for state. Dropdowns, modals, tabs, toasts → Alpine. Anything that reads/writes the database, or needs validation feedback → Livewire. Reaching for fetch() calls into custom JSON endpoints is the main way people break the kit's assumptions.

Tailwind v4 theming via CSS. Define brand colors, radii, and dark-mode variants with @theme / CSS variables in app.css. Consume them as bg-primary, text-muted, etc. Swapping themes then becomes editing ~20 lines of CSS, which is the whole point of "themeable."

Layout slots and Blade components for reuse. Cards, stat tiles, and empty states should be Blade components (<x-admin.stat-card>) taking props — not copy-pasted markup. This is where a 23-star kit pays off least: the component library is thin, so budget time to build your own primitives on top.

Testing. Livewire 4's Livewire::test(Component::class) covers most of the value. Add one happy-path and one authorization-failure test per screen; that catches the majority of regressions in admin panels.

Gotchas and Tips

The star count is the headline risk. At 23 stars this is a young project with a small maintainer surface. Expect thin docs, sparse issue history, and breaking changes between minor tags. Pin your versions, and assume you'll be reading source rather than documentation for anything non-obvious.

"Laravel 13 / Livewire 4 / Tailwind v4" means bleeding edge. All three are recent majors with their own migration guides. If your team is on Laravel 11/12 or Livewire 3, the kit will not drop in cleanly. Check framework compatibility before committing to the scaffold.

Tailwind v4 has no tailwind.config.js by default. Theme extension is @theme in CSS. Tutorials, editor plugins, and AI-generated code will constantly hand you v3-style config edits that silently do nothing. Keep the v4 docs open.

Dark mode flashes on first paint. With Alpine handling the toggle, the class is applied after hydration. Add a small inline <script> in <head> that reads localStorage and sets the class before render, or you'll get a white flash on every navigation.

Alpine/Livewire lifecycle collisions. Alpine state inside a Livewire-rendered subtree survives wire:navigate unpredictably. Use x-data on elements that Livewire doesn't re-render, and @entangle for anything shared. Also verify Alpine is loaded once — a duplicate Alpine.start() from a CDN tag plus the Vite bundle is a classic silent breakage.

Vite + wire:navigate asset staleness. If you add JS/CSS without restarting npm run dev, navigated pages can serve stale assets. Hard-refresh before debugging "my styles disappeared."

Seeder and permission assumptions. The default admin seeder often uses fixed credentials. Change them immediately, and check whether roles/permissions come from a package (Spatie, etc.) or bespoke columns — the authorization model determines every policy you write later.

Publishing vs. editing vendor files. If any part is a real package with vendor:publish, publish it. Editing vendor/ guarantees your changes vanish on the next composer update.

Extension points to favor: config file, nav registration array, Blade component slots, and Livewire component base classes/traits. Those are the seams that survive upstream changes. Hardcoded layout edits and direct route file rewrites are the seams that break.

Debugging admin-panel weirdness: check storage/logs/laravel.log for Livewire hydration errors first (they surface as generic 500s in the browser), then php artisan route:list --path=admin to confirm middleware actually applied, then verify @livewireStyles/@livewireScripts (or the v4 equivalent) are present exactly once in the layout.

Have an exit plan. Because it's a fork-and-own starter kit, your escape hatch is simply "keep the parts you like, replace the rest" — the code is already yours. That's the main reason a low-star starter kit is still reasonable here, provided you're comfortable owning the maintenance.