inertia start

v1.4.0

v1.4.0

This release adds complete OAuth authentication through Laravel Socialite, remembers the visitor's last login method, introduces reusable breadcrumb helpers, and strengthens the test and CI workflows.

Highlights

  • Users can log in and sign up with OAuth providers such as Google or GitHub, enabled with the new I_S_AUTH_PROVIDERS environment variable.
  • Provider logins link to existing accounts by verified email or create verified passwordless accounts, while keeping two-factor challenges and terms acceptance in place.
  • The login page shows a "Last used" badge on the method the visitor last logged in with.
  • Pages can replace or extend their layout's breadcrumb stack with static or reactive breadcrumb helpers.

Added

OAuth providers

  • Added the auth_providers option to config/inertia-start.php, built from the new I_S_AUTH_PROVIDERS environment variable. The value is a comma-separated list of Socialite driver names. Providers that are not listed return 404 on every OAuth route.
  • Added a google entry to config/services.php, reading GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, with {APP_URL}/auth/provider/google/callback as the redirect URL. Added I_S_AUTH_PROVIDERS, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET to .env.example.
  • Added App\Http\Controllers\Auth\OAuthController and its routes:
    • GET auth/provider/{provider}/redirect (oauth.redirect) and GET auth/provider/{provider}/callback (oauth.callback) to log in with a provider.
    • GET and POST auth/provider/{provider}/challenge (oauth.challenge, oauth.challenge.store) to complete a two-factor challenge.
    • POST signup/provider/{provider}/redirect (oauth.registration.redirect) to start from the registration page, and GET and POST signup/provider/{provider} (oauth.registration, oauth.registration.store) to accept the terms before the account is created. These routes use the guest and feature:accounts middleware.
  • Added the oauth_accounts table, the App\Models\OAuthAccount model, and User::oauthAccounts(). A provider user ID belongs to a single user, and a user can link one account per provider.
  • When a provider redirects back to the application:
    • An account already linked to the provider user ID is logged in.
    • Otherwise, the provider email is matched against existing users, and the provider account is linked on the first login.
    • When no user matches, a passwordless account is created with a verified email and the name returned by the provider. The provider is recorded as the context's registration method.
    • Providers exposing an email_verified flag, such as Google, must report the email as verified before it is used to match or create an account.
    • Users with two-factor authentication enabled must enter an authentication app code on the new auth/OAuthChallenge page.
    • When I_S_ACCOUNT_MUST_ACCEPT_TERMS is enabled, new users are sent to the registration page, which shows the provider email as read-only and requires accepting the terms before the account is created.
  • Added provider buttons to the login, switch account, and registration pages.
  • Added the AuthProvider TypeScript interface and the auth.oauth.*, messages.last_used, messages.last_used_tooltip, messages.continue_with_provider, and messages.oauth_providers.github translations in English, Spanish, and French.

Last used login method

  • Added a last_login_method cookie, kept for one year and configured under last_login_method_cookie in config/inertia-start.php. It is set after logging in with a password, a magic link, a passkey, or an OAuth provider, including the automatic login at the end of registration.
  • Added AuthService::rememberLoginMethod() and AuthService::lastUsedLoginMethod(). The latter only returns a built-in method (password, magic_link, passkey) or an enabled provider, and is passed to the login and switch account pages as the lastUsedLoginMethod prop.
  • Added App\Http\Responses\PasskeyLoginResponse, bound to the passkeys package's PasskeyLoginResponse contract. It responds like the package's default response and also records the passkey login method.
  • Added the LastUsedBadge component, displayed with an explanatory tooltip on the matching login button. PasskeyVerify gained a lastUsed prop.

Breadcrumbs

  • Added setBreadcrumbItems() to replace a page's breadcrumb stack and addBreadcrumbItems() to extend the defaults supplied by its layout.
  • Breadcrumb helpers accept static items or reactive getters, and layout breadcrumb props accept either a replacement array or a resolver that receives the default stack.
  • AppLayout, AdminLayout, and AccountLayout now resolve breadcrumb props consistently; account pages can extend or replace the built-in account breadcrumb.

Tests

  • Added feature coverage in tests/Feature/Auth/OAuthTest.php.
  • Added frontend unit coverage for replacing, extending, resolving, and reactively updating breadcrumbs.
  • AuthenticationTest and RegistrationTest now assert the last used login method cookie after password, magic link, passkey, and post-registration logins.

Changed

  • Split the Composer test workflow into test:backend and test:browser. composer run test runs both, while composer run ci:check also runs ESLint, Prettier, vue-tsc, and the frontend unit tests.
  • Browser tests now use and clear a dedicated Vite hot file, preventing a stale development server marker from leaking into the test environment.
  • CI now installs Node development dependencies explicitly and runs application setup non-interactively.
  • Removed generated IDE Helper stubs from Composer, PHPStan, models, and CI. Larastan now infers model properties from migrations, while Laravel-aware editor support provides completion and navigation without generated project files.
  • Updated the bundled Inertia Start AI skill to describe the implemented OAuth flow and its security requirements.
  • TooltipContent now uses the secondary color for the background instead of the foreground color, and its arrow has a smaller radius. This applies to every tooltip in the application.
  • Added crawler directives for /auth/provider/ and /signup/provider/ to ask crawlers not to visit OAuth endpoints.
  • Synced with laravel/vue-starter-kit up to commit 4bd3e1d, and documented why Inertia Start intentionally does not adopt every upstream feature.

Fixed

  • Made avatar upload and account export tests explicitly enable the avatar feature, preventing environment-dependent failures.

Dependencies

  • Added laravel/socialite 5.31.
  • Removed barryvdh/laravel-ide-helper to avoid duplicate definitions. This package was previously valuable for completion and navigation, but modern Laravel-aware editor tooling and Larastan now provide those capabilities.
  • Updated Laravel Framework to 13.32, Laravel Boost to 2.9, Pest to 5.2, Playwright to 1.63, and other minor and patch Composer and npm dependencies.

Upgrade Guide

  1. Run composer install.

  2. Run npm install.

  3. Run php artisan migrate to create the oauth_accounts table.

  4. Rebuild frontend assets with npm run build or your normal frontend workflow.

  5. OAuth stays disabled while I_S_AUTH_PROVIDERS is empty. To enable Google, create an OAuth client in the Google Cloud console with {APP_URL}/auth/provider/google/callback as an authorized redirect URI, then add its credentials to your .env file:

    I_S_AUTH_PROVIDERS=google
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

  6. To enable another Socialite provider, add its credentials to config/services.php with {APP_URL}/auth/provider/{provider}/callback as the redirect URL, add its driver name to I_S_AUTH_PROVIDERS, and add messages.oauth_providers.{provider} to each locale's messages.php. Emails from providers that do not expose an email_verified flag are trusted as returned, so only enable providers that return verified email addresses.

  7. If you customized resources/js/pages/auth/Login.vue, resources/js/pages/auth/RequestRegistration.vue, or resources/js/components/OAuthProviderButton.vue, merge the provider buttons and last used badges. OAuthProviderButton now expects an AuthProvider object in its provider prop instead of a string.

  8. If you bound your own implementation of Laravel\Passkeys\Contracts\PasskeyLoginResponse, merge it with App\Http\Responses\PasskeyLoginResponse and call AuthService::rememberLoginMethod(AuthService::LOGIN_METHOD_PASSKEY), so passkey logins keep being remembered.

  9. If you customized resources/js/components/ui/tooltip/TooltipContent.vue, or relied on the previous tooltip colors, review the new styles.

  10. If you customized AppLayout, AdminLayout, or AccountLayout, merge the new BreadcrumbItemsProp and resolveBreadcrumbItems() support. Existing static breadcrumb arrays remain supported.

  11. If you customized the Composer test scripts or GitHub Actions workflow, merge the split backend/browser commands, frontend unit test execution, explicit Node dependency installation, and non-interactive setup.

  12. If your editor relied on generated _ide_helper.php, _ide_helper_models.php, or .phpstorm.meta.php files, enable PhpStorm's bundled Laravel support, Laravel's official VS Code extension, or Laravel's official language server instead.