Genesis Laravel Package

Getting Started

Genesis is a starter kit, not a library — it has zero dependents because you don't composer require it into an existing app. You scaffold a new project from it (via composer create-project devdojo/genesis my-app or by cloning the repo), then treat the resulting codebase as your own application.

Minimal first run:

composer install
cp .env.example .env
php artisan key:generate
# set DB_* in .env
php artisan migrate --seed
php artisan storage:link
npm install && npm run dev
php artisan serve

Log in with the seeded admin account (check database/seeders/DatabaseSeeder.php and the README for credentials — change them immediately), then visit the admin/dashboard route.

Where to look first, in order:

1. routes/web.php (and routes/auth.php / routes/api.php if present) — the route groups tell you the auth, dashboard, admin, and public boundaries.
2. app/Http/Controllers/ and especially app/Http/Controllers/Admin/ — the CRUD conventions.
3. resources/views/ and resources/views/components/ — reusable Blade primitives.
4. database/seeders/ and database/migrations/ — roles, permissions, settings, and the initial data model.
5. tailwind.config.js + the layout Blade file — theme tokens and dark-mode wiring.

First useful exercise: copy an existing admin resource (e.g. the users or announcements CRUD) end-to-end into a new "Links" module — model, migration, form request, controller, Blade index/create/edit views, sidebar link, and policy. This teaches you the kit's naming, validation, and layout conventions faster than reading docs.

Implementation Patterns

Follow the shipped CRUD shape. Genesis admin modules typically follow model → migration → FormRequest → resource controller → Blade index/create/edit → sidebar entry → policy. Match existing naming and view structure; the value of a starter kit is consistency, and deviating early makes future merges painful.

Extend auth in place. Adding profile fields (bio, avatar, timezone) means: new migration, update the profile update controller/request, update the profile Blade form, and update the User factory. Don't replace the auth stack — the views, routes, and password-reset flows are already wired.

Roles and permissions as the authorization layer. Seed roles in the seeder, gate admin route groups behind role middleware, and use @can / policies in views rather than inline if (auth()->user()->isAdmin()) checks. Eager-load roles in admin listings (with('roles')) to avoid N+1s in user tables.

Theming via Tailwind + a persisted preference. The kit's dark/light/system switch usually combines a Tailwind dark class strategy, localStorage or a user setting, and an inline script in <head> to set the class before paint. Add new design tokens to tailwind.config.js rather than hardcoding colors in views.

Settings and feature flags. Key-value settings (site name, toggles, announcement banners) are usually a model with cached reads. When adding a setting: add a migration/seed default, a cached accessor, and a field in the admin settings form — and clear the cache on save.

Interactivity: Alpine for small state, Livewire for forms. Keep to the stack the kit ships with. Use Blade components with @props and slots instead of duplicating markup.

API and integrations. Sanctum tokens for first-party/mobile clients; put new endpoints in routes/api.php and scope with abilities. For billing (Cashier/Stripe if included), keep the webhook route in routes/api.php or exclude it from CSRF, and test locally with the Stripe CLI.

Testing. Use RefreshDatabase plus a base test case that seeds roles and permissions. actingAs($user) after attaching the right role keeps authorization tests honest.

Gotchas and Tips

• No upgrade path. With dependents: 0 and starter-kit status, there's no composer update to pull in fixes. Laravel upgrades are manual diffs against a fresh kit. Keep your changes in clearly owned files (custom controllers, own namespace, own views) so future comparisons stay readable.
• Change seeded credentials before deploy. The default admin user is a known quantity. Remove or gate the demo seeder in production.
• Never migrate:fresh --seed against anything real. It's tempting during development; it will drop your data.
• Permission/role cache staleness. After seeding or editing roles, run php artisan permission:cache-reset (Spatie) or cache:clear; otherwise @can checks look wrong.
• Tailwind JIT misses dynamic classes. bg-{{ $color }}-500 won't be generated. Use full class names in maps or safelist them in tailwind.config.js.
• Dark-mode flash (FOUC). If the theme class is applied in JS after load, users see a white flash. Put the theme-init script inline in <head> before the stylesheet.
• storage:link is required for avatars and uploads; missing symlinks produce silent 404s on images that "worked locally."
• Vite manifest errors mean you're running php artisan serve without npm run dev, or forgot npm run build for production. Check @vite directives.
• Queues. Database notifications and mail need a worker (php artisan queue:work) or QUEUE_CONNECTION=sync locally. Otherwise notifications silently never appear.
• config:cache hides .env changes. Use config('...') in code, never env() outside config files, and re-cache after edits.
• Route caching and closures. If route:cache fails, a closure route is the culprit — convert it to a controller action.
• CSRF on webhooks. External callbacks (Stripe, GitHub, etc.) must be excluded in VerifyCsrfToken or moved to the API stack.
• Impersonation needs guardrails. If the kit supports "log in as user," restrict it to admins, forbid impersonating other admins, and log the actor.
• Don't publish-and-edit vendor views casually. Once published they freeze; track what you've overridden so upstream fixes aren't silently lost.
• Blade hygiene. Keep queries and auth logic out of views; use components, policies, and view composers so the admin templates stay maintainable as you add modules.