Ui Laravel Package

Getting Started

laravel/ui gives you two things: frontend presets (bootstrap, vue, react) and a full session-based auth scaffold (--auth) that is copied into your application as ordinary, editable code.

Check the version matrix first — only the latest major gets fixes:

Minimal path (fresh-ish app, classic Blade + Bootstrap login):

composer require laravel/ui
php artisan ui bootstrap --auth     # scaffolds auth + frontend preset
npm install
npm run dev                         # or: npm run build
php artisan migrate                 # users table already exists in modern skeletons

Then hit /register, /login, /home.

Where to look first, in this order:

First real use case: an internal admin/CRUD tool that needs working registration, login throttling, password reset and email verification in an afternoon, on top of a Bootstrap design you don't mind. If you need API tokens, 2FA, teams or social login out of the box, stop here and use Breeze or Jetstream — laravel/ui won't scaffold any of that.

Implementation Patterns

1. Selective auth routes instead of full scaffolding. Auth::routes() accepts options and is the primary day-to-day lever:

// Invite-only internal app: no public signup, no self-service reset
Auth::routes(['register' => false, 'reset' => false, 'verify' => true]);

Supported keys: login, logout, register, reset, confirm, verify, plus email in some versions — check src/Auth/AuthRouteMethods.php in the installed version rather than trusting a tutorial, since the option set has drifted across majors.

2. Publish, then own the controllers. The generated controllers are yours; treat them as application code, not vendor code. Common customisations:

// app/Http/Controllers/Auth/LoginController.php
public function username()          { return 'username'; }          // login by username
protected function credentials(Request $request)                      // add tenant scope
{
    return $request->only($this->username(), 'password') + ['tenant_id' => tenant()->id];
}
protected function loggedOut(Request $request)                        // audit trail
{
    activity()->log('logout');
    return redirect('/');
}

AuthenticatesUsers, RegistersUsers, ResetsPasswords, VerifiesEmails, ConfirmsPasswords traits are all trait-based, so overriding one method is cheaper than rewriting the controller.

3. Company preset via a macro. Presets are macroable — the intended extension point for "every new service in our org starts with the same scaffolding":

// app/Providers/AppServiceProvider.php :: boot()
use Laravel\Ui\UiCommand;
use Illuminate\Support\Facades\File;

UiCommand::macro('acme', function (UiCommand $command) {
    $command->info('Scaffolding the Acme design system…');
    File::copyDirectory(base_path('stubs/acme/views'), resource_path('views'));
    File::copyDirectory(base_path('stubs/acme/js'), resource_path('js'));
    $command->call('ui', ['type' => 'bootstrap', '--auth' => true]);
    $command->info('Done. Run npm install && npm run dev.');
});

Then php artisan ui acme. Macros are just closures on the command, so you can prompt with $command->confirm(), run $command->call() for sub-steps, or refuse to run if app/Http/Controllers/Auth already exists.

4. Layering a real design system on top. Generate the scaffold once, then keep the contract (route names, field names, controller validation) and replace only the Blade views with your component library:

• Field names must stay email, password, password_confirmation, remember.
• Forms must post @csrf to the named routes (login, password.email, password.update, …).
• Reset links hit password.reset with token + email query params — don't rename those.

5. Swapping the frontend preset. php artisan ui react on an app already scaffolded with vue rewrites resources/js/app.js, bootstrap.js and package.json, so do it on a branch and diff. The auth screens stay Blade + Bootstrap in every preset — React/Vue only affect your JS entry point.

6. Testing generated auth. Feature tests against the real routes catch most regressions:

Notification::fake();
$this->post('/password/email', ['email' => $user->email])->assertSessionHas('status');
Notification::assertSentTo($user, ResetPassword::class);
$this->post('/login', ['email' => $user->email, 'password' => 'secret'])->assertRedirect('/home');

7. Migrating off Auth::routes(). Because the route registration lives in the package, teams that want a single hand-written routes/auth.php typically: copy the route block out of vendor/laravel/ui/src/Auth/AuthRouteMethods.php, adapt it, delete the Auth::routes() call, and only then can they drop the Composer dependency.

Gotchas and Tips

• Auth::routes() does not exist without this package. It's a macro registered by Laravel\Ui\UiServiceProvider. Removing laravel/ui from composer.json after scaffolding produces Method Illuminate\Routing\Router::auth does not exist. Either keep the dependency or inline the routes first.
• Route names are hardcoded, so you can't call Auth::routes() twice. Two guards (admin + customer) means hand-writing the second set with a prefix and renamed routes (admin.login), not a second Auth::routes() call. Same reason it can't be used for API auth.
• It must live in the web middleware group (i.e. routes/web.php). Putting it in a group without StartSession/VerifyCsrfToken gives you 419s and "session store not set on request".
• POST /logout only. Older tutorials show GET /logout; you'll get a 405. Change the generated form, not the route.
• verify => true needs the model too. App\Models\User must implement Illuminate\Contracts\Auth\MustVerifyEmail, and the verified middleware alias must exist (Laravel 8+ has it). Otherwise the verification routes exist but nothing enforces them.
• RouteServiceProvider::HOME is the redirect target baked into LoginController, RegisterController and VerificationController. Change /home to /dashboard everywhere, or logins silently land on a 404.
• Bootstrap 5 since 3.4.0. Old tutorials use BS4 markup (form-group, input-group-append, custom-control). If your generated views use mb-3/form-label, you're on Bootstrap 5 — mix the two and the layout collapses.
• Vite vs Mix split at 4.0.0. On 4.x you get vite.config.js + @vite([...]) in the layout; on 3.x you get webpack.mix.js. Installing the latest package into a Mix-era app produces a layout that references a Vite build that doesn't exist — pin laravel/ui:^3.4 or migrate to Vite.
• @vite throws "Vite manifest not found" until you run npm run dev or npm run build. The scaffolded layout doesn't degrade gracefully, which bites in CI and on fresh deploys.
• Re-running ui / ui:auth re-copies stubs. There's no tracking of what it generated and no merge — customised layouts/app.blade.php and Auth/*Controller.php can be clobbered. Commit before re-scaffolding and diff afterwards. Same reason it won't clean up files the previous preset left behind when you switch vue → react.
• The preset edits package.json by decoding and rewriting it. A JSON syntax error or a comment in the file means the dependency block is silently not updated. Verify bootstrap, sass and laravel-vite-plugin actually landed after scaffolding.
• Vue preset lineage matters. The scaffolded ExampleComponent.vue and the Vue.component(...) registration style are Options-API / Vue 2-era. Before following a Vue 3 <script setup> tutorial, check the vue version the preset put in package.json (and remember npm run dev after every component change, or npm run watch).
• Login throttling is 5 attempts per email+IP, keyed on the lowercased/transliterated email. If your users can register with mixed-case emails and you query case-sensitively elsewhere, the throttle key and your lookup will disagree — normalise at registration.
• password_timeout in config/auth.php (default 10800s) controls the confirm-password window; users reporting "it asks again too often" are usually hitting this, not a bug.
• No API/Sanctum scaffolding, no password broker changes, no rate-limit bypass for tests. For tests that hammer login, RateLimiter::clear() or withoutMiddleware(ThrottleRequests::class).
• Package status: README explicitly calls this legacy. Only 4.x receives bug fixes, so don't expect backports; new projects should default to Breeze (Blade/Livewire/React/Vue, Tailwind, Sanctum) or Jetstream. Use laravel/ui when you specifically want the classic Bootstrap auth views, or when maintaining an app already on it.