Auth Laravel Package

Getting Started

What it is: devdojo/auth is a batteries-included auth scaffolder for Laravel — login, registration, password reset, email verification, email-based 2FA, profile editing, social login, and an admin user-management screen — shipped as Livewire components with Blade/Tailwind views. It's the "one command instead of Breeze + three other packages" option.

As of v2.2.0 the bundled views ship Tailwind CSS v4 markup. That matters before you type anything: the package's views assume a v4 pipeline (@import "tailwindcss", @source, CSS-first @theme config). If your app is on Tailwind v3 you have a decision to make up front — upgrade the app, stay on devdojo/auth:^2.1, or isolate the auth views — see the gotchas.

Minimum steps:

composer require devdojo/auth
php artisan auth:install
npm install && npm run dev   # if you're using the bundled UI

The installer publishes config, migrations, routes, and views, runs migrations, seeds roles, and typically prompts you to create an admin user. Verify by visiting /login, /register, and the admin area (usually /admin or /admin/users).

Tailwind v4 prerequisites (only if you're consuming the bundled UI rather than your own layout):

npm install tailwindcss@^4 @tailwindcss/vite   # or @tailwindcss/postcss

/* resources/css/app.css */
@import "tailwindcss";
@source "../../vendor/devdojo/auth/resources/views";
@source "../../resources/views";

Where to look first, in order:

1. The published config file (in config/, printed by the installer). This is the switchboard: registration on/off, email verification, 2FA, social providers, post-login/redirect targets. Read it end-to-end before touching any view.
2. Your resources/css/app.css — new in v2.2.0, this is now where styling lives. In v4 the "config" is CSS: @theme for tokens, @source for content paths. There may be no tailwind.config.js in the project at all, and that's correct.
3. routes/web.php — the installer appends/registers the auth route group. Run php artisan route:list --path=auth to see exactly what's live for your config.
4. app/Models/User.php — check what the installer changed: MustVerifyEmail, role/two-factor traits or relationships, fillable fields.
5. Published views (under resources/views/) — this is where layout, copy, and social buttons live.
6. config/services.php — only if you enable social login.

First real use case: replacing a half-finished Breeze install with a working, styled auth stack including an admin user list in a single afternoon, then layering your own profile fields on top.

Implementation Patterns

Drive behavior from config, not from view edits. Nearly every feature toggle (registration, verification, 2FA, providers, redirects) is a config key. Keeping changes there means composer update won't blow away your work. Only publish/edit views when you need presentation changes.

Theme through @theme, not through view edits. With v4 the natural place to restyle the auth screens is your app CSS: define brand colors, radii, and font tokens once in @theme, and the package's utility classes pick them up. This is now a cheaper and more upgrade-proof path than editing published Blade markup.

Guard your app around the package, not inside it. Give your application routes the standard auth (and your own verified, admin) middleware and let the package own /login, /logout, /register. Configure the post-login redirect centrally rather than hardcoding redirect()->intended() in controllers.

Roles and the admin screen. The installer seeds roles and an admin user. From there:

// Route-level gate
Route::middleware(['auth', 'can:viewAny,App\Models\User'])->group(function () {
    // your admin-adjacent pages
});

Prefer a policy or a small isAdmin()-style check over editing the vendor admin component. Existing users created before install won't have roles — plan a backfill migration or artisan command.

Social login pattern. Enable providers in config, add credentials to config/services.php / .env, ensure Socialite is installed, and add buttons to the published login/register Blade views pointing at the package's redirect route. Test callback URLs against both APP_URL and your production domain — mismatches are the #1 failure here.

Custom profile fields. Publish the profile view, add fields to the form component's validation and to the users migration (or a side table), and update $fillable. Keep the package's update logic as the base; don't fork it wholesale.

Testing pattern. Use actingAs($user) against your own routes, and hit the package's routes directly for smoke tests. In phpunit.xml, disable 2FA and email verification so tests don't chase mail. For 2FA flows specifically, use Mail::fake() and assert on the code notification rather than the full round-trip.

Deployment pattern. Run auth:install once, locally, commit the published files, then deploy with php artisan migrate --force && php artisan config:cache && php artisan route:cache. Never run the installer in CI or production — it's interactive and overwrite-prone. Build assets in CI with a Node version that satisfies Tailwind v4 (Node 20+).

Upgrading from a pre-2.2 install. Treat it as a styling migration, not a patch bump: re-publish views, move any tailwind.config.js content-path entries into @source rules, replace @tailwind base/components/utilities with @import "tailwindcss", swap the PostCSS plugin, then eyeball every auth screen in a production build.

Gotchas and Tips

• Tailwind v3/v4 mismatch is the new top failure. v2.2.0's views use v4 syntax and utilities; compiling them under a v3 pipeline produces unstyled or partially styled pages, and tailwind.config.js content entries do nothing in v4. Decide explicitly: upgrade the app to v4, pin devdojo/auth:^2.1, or scope the package's CSS separately. A half-migrated setup (v4 installed, old @tailwind directives still in app.css) silently produces almost no styles.
• Content detection moved. In v4 you no longer register view paths in tailwind.config.js; you write @source "../../vendor/devdojo/auth/resources/views"; (and any path you override) in your CSS entrypoint. If auth pages render unstyled in a production build but look fine in npm run dev, a missing @source is the first thing to check.
• Browser support narrowed. Tailwind v4 targets modern browsers (roughly Safari 16.4+, Chrome 111+, Firefox 128+). If you have an enterprise or kiosk audience on older browsers, v4 auth pages may degrade — pin the package to 2.1.x in that case rather than patching the views.
• Route collisions are the other top failure. /login, /register, /logout will fight with Breeze, Jetstream, Filament, or your own routes. Uninstall the old scaffolding first, then check php artisan route:list for duplicates. Silent 404s or "route not defined" usually mean two packages claiming the same URI.
• The installer overwrites. Commit (or stash) before running auth:install, then read git diff. It can touch User.php, views, migrations, and now your CSS entrypoint. Treat the diff as a code review, not a formality.
• Published views are frozen. composer update will not update them. When a release fixes a view, you must re-publish and re-apply your customizations. Keep your view edits small and documented, or better, override via your own layout.
• Mail configuration is load-bearing. Email verification and email-based 2FA both require working mail. With MAIL_MAILER=log locally, users get stuck in verification loops and 2FA codes appear only in storage/logs/laravel.log. Verify with Mailpit/Mailhog before blaming the package.
• Cache clearing after config changes. Route registration is config-driven. After toggling registration or 2FA, run php artisan optimize:clear — stale route:cache/config:cache will make it look like your change did nothing.
• Session driver matters with 2FA. Use the database (or Redis) session driver; file sessions plus multi-step 2FA on load-balanced hosts produce intermittent "code invalid" reports.
• Don't edit vendor/. For hooks, use Laravel's standard auth events (Login, Registered, Verified) and listeners, or a small service provider that decorates the package's Livewire components. Extension points are config keys, published views, CSS tokens, and events — not vendor patches.
• Pin the version. With a fast-moving package, composer require devdojo/auth:^x.y and review the changelog before upgrading; config keys, view paths, and the Tailwind major version occasionally move between minor releases. v2.2.0 is a styling-major change shipped under a minor number — read it as such.
• Debugging checklist when a flow breaks: route:list for registration → check the config key → optimize:clear → check storage/logs/laravel.log for mail/Livewire errors → confirm the view is the published one (not a stale cached copy) → verify middleware on the route group → for styling only, check @source paths and that the build is actually Tailwind v4.