Admin Dashboard Template Laravel Package

Getting Started

This is a starter kit / template repository, not a Composer package — you don't composer require it, you scaffold a project from it. That distinction shapes everything about how you'll use it day to day.

Scaffold and boot:

laravel new my-app --using=salimi-my/admin-dashboard-template --pnpm
cd my-app
pnpm install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed
pnpm dev   # and `php artisan serve` in a second terminal

The --pnpm flag matters: the template ships a pnpm-lock.yaml and Vite/shadcn tooling that assumes pnpm. Using npm or yarn will work but you'll lose the lockfile and may hit peer-dependency resolution differences with React 19.

Where to look first, in order:

1. app/Enums/UserRole.php and app/Policies/UserPolicy.php — this pair defines the entire authorization model. Read them before anything else; every admin surface is gated through them.
2. routes/ — then immediately look at resources/js/routes/ (Wayfinder output). The two are coupled and the generated files are your real reference for what URLs exist.
3. resources/js/pages/ — one directory per feature area (dashboard, users, settings, auth). The users directory is the canonical example of the server-driven table pattern.
4. resources/js/components/ui/ — the shadcn/ui set. Resist editing these directly; wrap them.
5. config/fortify.php — 2FA and email verification feature flags live here and control whether whole UI branches render.

First use case you'll almost certainly hit: adding a new admin resource (say, Project) behind the same auth/role gate as Users. Get the Users feature working end-to-end first — create, edit, delete, bulk delete — because you'll be copying its shape. The fastest path is to duplicate the users page directory, the UserController, and the datatable query, then rename. Expect roughly an hour for a simple resource once you understand the pattern.

Demo logins are documented in the README and created by the seeder — use them to confirm the scaffold is healthy before you start changing things.

Implementation Patterns

Server-driven datatables. The users table does not sort, filter, or paginate client-side. Search/filter/sort/page all round-trip to the controller via Inertia partial reloads, and the server returns paginated rows plus metadata. Day-to-day this means:

• Table state lives in the URL query string, not React state. Preserve that — it gives you shareable links and back-button behavior for free.
• Use Inertia's only: [...] on reloads so you don't resend unrelated props on every keystroke:

router.get(route('users.index'), params, {
  preserveState: true,
  preserveScroll: true,
  only: ['users', 'filters'],
});

• Debounce search input (~300ms) before firing. Every keystroke is an HTTP request otherwise.
• Bulk delete should send an ID array in one request and return a fresh page of rows; don't loop client-side deletes.

Typed routes via Wayfinder. Never write '/admin/users/' + id. Use the generated functions:

import { index, store, destroy } from '@/routes/users';

Run the generator whenever routes change (pnpm build or the dedicated artisan command — check composer.json / package.json scripts for the exact hook). Wire it into your dev loop, not just CI, or you'll get phantom TypeScript errors from stale route files.

Forms. Use Inertia's useForm with the shadcn form primitives. The dialogs (create/edit/delete) follow a consistent pattern: useForm → submit → onSuccess closes the dialog and resets. Copy that shape rather than inventing a new one; the error display wiring between Laravel validation responses and the shadcn <FormMessage> component is the fiddly part and it's already solved there.

Authorization. Roles are a UserRole enum cast on the model, and UserPolicy is the enforcement point. The idiomatic day-to-day pattern:

// controller
$this->authorize('viewAny', User::class);

and mirror the same condition in the frontend for UI affordances only (hiding a delete button), never as the actual gate. If you add a role, update the enum, the policy, the seeded data, and any role-distribution chart query — four places, easy to miss one.

Settings are a template for user-owned resources. Profile/avatar/password/2FA/appearance are four separate forms against the same ProfileController-style surface. When you need "user uploads a thing," the avatar upload (disk config, storage:link, old-file cleanup) is your reference implementation.

Layout composition. Sidebar, header, breadcrumbs, and footer are separate components composed in an app layout. Adding a nav entry is a data change in the sidebar config, not a JSX edit — find that config file early and treat it as the single source of navigation truth so breadcrumbs and the active-state highlighting stay consistent.

Gotchas and Tips

Template drift is the big one. Because this is a laravel new --using scaffold, you get a snapshot. There is no composer update that pulls template improvements, and git pull from upstream will conflict with everything you've built. If you want to track upstream fixes, add the template as a upstream remote at scaffold time and cherry-pick deliberately — but for a v1.0.0 template, plan to own the code. Budget for a manual diff-and-merge pass if a v1.1.0 lands with security-relevant changes.

Laravel 13 is brand new. Third-party packages in your own dependency list may not have caught up. Before you install anything, check its laravel/framework constraint. This is the most likely source of day-one friction, and it's not the template's fault.

radix-vega style differs from default shadcn/ui. Copy-pasting components from the shadcn docs site or from tutorials will produce subtly wrong spacing, radii, and color tokens. Use pnpm dlx shadcn@latest add <component> with the repo's existing components.json so new components inherit the vega style, or port the docs example into the local conventions by hand.

Tailwind v4 config is CSS-first. There's no tailwind.config.js doing the work you're used to. Theme tokens — including the dark mode palette — live in CSS via @theme. Editing dark mode means editing CSS variables, and a mismatch between the .dark class strategy and your provider will give you a flash of light theme on load. If you see FOUC, look at the inline theme-init script in the root Blade template first.

2FA will block your test suite. Fortify's two-factor challenge is real middleware. In tests, either confirm the 2FA feature flag is off in config/fortify.php under the testing environment, or explicitly actingAs a user with two_factor_confirmed_at null and assert the redirect. Tests that just actingAs($admin)->get('/users') will intermittently fail once you enable 2FA, which is a confusing failure the first time.

storage:link and file permissions. Avatar upload silently no-ops to a broken image if the symlink is missing or the public disk isn't configured. This is the single most common "it worked yesterday" report. Run php artisan storage:link as part of setup docs.

Larastan will be stricter than you expect. Run composer lint / the static analysis script before pushing. Errors will cluster around Inertia prop array shapes and enum casts in queries — annotate rather than suppress. Suppressions accumulate fast in a template-derived codebase.

Authorization isn't route middleware. Policies are invoked in controllers. A new route added without the corresponding authorize() call is unprotected even though it sits under an /admin prefix. Grep for authorize when reviewing new endpoints, and consider adding a Pest test per admin route that asserts a non-admin gets a 403 — this catches the omission cheaply.

Pagination + filters + bulk delete interact badly. If you bulk-delete every row on page 3, the client may request a now-nonexistent page and render empty with a valid-looking paginator. Handle it server-side by clamping the page number after deletion.

Extension points worth knowing: the sidebar nav config, UserRole enum, UserPolicy, the datatable query builder in the users controller, the shadcn theme variables, and config/fortify.php. Those six files cover most day-to-day customization; everything else is either generated (Wayfinder routes, components/ui) or boilerplate you should leave alone.

Overall: a well-scoped, sensibly opinionated admin foundation with modern tooling and an unusually complete example feature (users) to copy from. Treat v1.0.0 as a starting point you fork and own, verify the Laravel 13 dependency situation for your own packages, and lean on the Users feature as your reference implementation for everything else.