Starter Kit Laravel Package

Getting Started

This is a starter kit, not a runtime dependency — you consume it once at scaffold time and then own the generated codebase. There is no composer require upgrade path; treat the repo as a template you fork or diff against.

Prerequisites: PHP 8.4+, Composer, Node 20+, and a database. Verify the composer.json constraints after scaffolding, since Laravel 13 and Livewire 4 are recent majors.

Scaffold:

laravel new my-application --using=nidhyatechnologies/starter-kit
cd my-application

Then configure .env, run php artisan migrate, and build assets with npm install && npm run build (or npm run dev).

There is no default administrator. v1.0.0 removed the auto-created admin, so a fresh install has zero privileged users. To get into the user/role/permission screens:

php artisan db:seed --class=DemoUserSeeder

…or register a user and attach the Super Admin role manually. Do the seeding before you go looking for the admin UI, otherwise you'll conclude the install is broken.

Where to look first, in order:

1. routes/web.php and routes/settings.php — the route map for the whole admin surface.
2. app/Livewire/ — the SPA-style admin screens (users, roles, permissions, profile, security).
3. app/Policies/ and the Super Admin guard — this is where privilege rules actually live.
4. config/fortify.php — which auth features are on.
5. The permissions/roles seeder — the canonical list of abilities your @can checks must match.
6. resources/sass/app.scss — Bootstrap variable overrides and branding.

First real use case: log in as the demo admin → create a role with a narrow permission set → invite a new user via the Users screen → assign that role → confirm the invited user is forced through password setup and sees only their permitted navigation. That single loop exercises Fortify invitations, Spatie permissions, the password-update enforcement flag, and the audit log — the four things most likely to surprise you.

Implementation Patterns

Build new modules by copying the existing CRUD shape. The user management screen is the reference implementation: a Livewire component with search/filter/pagination state, a form object for validation, a policy for authorization, and audit events dispatched on write. New domain entities should follow the same layering rather than inventing a second convention — consistency here is what makes the starter kit pay off.

Authorization is the load-bearing pattern. Use @can / Gate::allows in Blade and $this->authorize() in Livewire actions, driven by Spatie permissions. Keep the seeder as the single source of truth for ability names and add new permissions there rather than ad-hoc in the database. For anything that delegates roles, go through the provided privilege-aware delegation path — do not let a form accept an arbitrary role ID and call assignRole directly, or you've quietly created a privilege-escalation hole the Super Admin guards were meant to prevent.

Audit logging is event-driven — extend, don't bypass. When you add a sensitive action (impersonation, bulk export, API token generation), emit through the same audit event/observer the kit already uses for user, role, permission, profile, password, and security events. Writing audit rows directly with DB::table() will produce entries that miss the actor/context shape your UI expects.

Theming stays in Sass. Override Bootstrap variables at the top of resources/sass/app.scss before Bootstrap is imported; changing colours from the compiled CSS or with inline styles will fight the build. Tailwind was removed in v1.0.0, so any pre-built component you paste in needs its Tailwind classes translated to Bootstrap equivalents.

Treat the test suite as documentation. Feature tests, browser smoke tests, static analysis, formatting, and dependency audits all ship configured. When adding a module, mirror the existing test structure — and run the browser tests locally at least once, because CI-specific failures (missing Chrome, driver mismatch) are the most common "works on my machine" trap in this stack.

Upstream changes require manual diffs. Since you can't composer update a starter kit, keep a note of the commit you scaffolded from and diff later releases into your app. This matters more than usual while Laravel 13 / Livewire 4 are both young.

Gotchas and Tips

No admin on install is the #1 trip-up. Fresh scaffolds have no privileged account. Seed DemoUserSeeder locally, but never in production — it creates known credentials. If you must run it outside local, use --force deliberately and delete the user immediately after; better, create your first admin via a one-off tinker script or a private seeder excluded from the repo.

Spatie permission cache goes stale. After changing roles or permissions programmatically (seeders, migrations, tinker, background jobs), run php artisan permission:cache-reset — or you'll chase phantom @can failures where the DB clearly says the user has the permission. In tests, reset the cache in setUp or between assertions.

The Super Admin safeguards are UI-layer, not database-layer. They prevent deletion/demotion through the admin screens. Seeders, direct model calls, and raw queries bypass them entirely. If you add a new destructive path (an artisan command, an API endpoint), you must re-implement the guard yourself.

Suspension only works where the check is applied. Account suspension relies on middleware/a guard on the authenticated routes. New route groups or custom guards you add will silently let suspended users through unless you attach the same middleware.

Password-update enforcement is a flag, not a force. Invited users and reset flows set a "must change password" state; verify your own added routes respect it, or users can navigate around the prompt with a direct URL.

Tailwind is gone — snippets will look broken. Any tutorial, forum answer, or Livewire component you copy that uses flex items-center px-4 etc. will render as unstyled block elements. Translate to Bootstrap classes. Same for Livewire pagination: it's Bootstrap-styled, so don't publish default views expecting Tailwind markup.

Invitations need working mail. Locally set MAILPIT / Mailhog / MAIL_MAILER=log before testing invitations — a silent queue or missing SMTP config makes the invite flow appear to no-op with no error surfaced.

Session management assumes database sessions. Set SESSION_DRIVER=database and run the sessions migration; otherwise the "active sessions" screen has nothing to show.

Two-factor recovery codes are stored encrypted and regenerating invalidates the old set. Don't script regeneration for support requests — you'll lock users out of their backup path.

Fortify views: don't vendor:publish blindly. The kit ships customized Fortify views; publishing the vendor defaults overwrites them and drops the Bootstrap styling. Publish only when you intend to replace a specific view, and check git diff afterwards.

Browser tests need real Chrome. CI installs browser dependencies; locally you'll need a Chrome/Chromium binary and a matching driver. These tests are also the slowest part of the suite — tag or group them so the fast feature tests stay usable in a tight loop.

Check Laravel 13 / Livewire 4 package compatibility before adding dependencies. Ecosystem support for both majors is still filling in; a package with laravel/framework: ^11|^12 in its constraints will either fail to install or install and misbehave.