laravel-nuxt-ui-inertia-template/README.md

Laravel + Nuxt UI + Inertia Template

A starter template built with Laravel 13, Inertia.js v3, Vue 3, Nuxt UI, and Tailwind CSS v4.

Stack

• Backend: Laravel 13, PHP 8.5
• Frontend: Vue 3, Inertia.js v3, TypeScript
• UI: Nuxt UI v4 (Dashboard components), Tailwind CSS v4
• Validation: Valibot (frontend), Form Requests (backend)
• Database: PostgreSQL
• Testing: Pest v4, Vitest
• Dev Environment: Laravel Sail (Docker)

Features

• Authentication — Login (email or username), register, forgot/reset password
• Social Login — OAuth via Laravel Socialite with provider tracking (social_accounts table)
• Email Verification — Optional, toggle via AUTH_ENABLE_EMAIL_VERIFICATION
• Two-Factor Authentication — Optional TOTP and recovery-code protection, toggle via AUTH_ENABLE_TWO_FACTOR
• Dashboard — Protected page using Nuxt UI dashboard components with auth + verified middleware
• Security — Nullable passwords for social-only users, verified-email requirement for provider linking, rate limiting on all auth endpoints
• Code Quality — ESLint, Laravel Pint, shared Valibot validation schemas

Getting Started

# Clone and install
composer install
cp .env.example .env

# Start Sail
vendor/bin/sail up -d

# Setup
vendor/bin/sail artisan key:generate
vendor/bin/sail artisan migrate
vendor/bin/sail npm install
vendor/bin/sail npm run build

Development

# Start Sail (server, database, etc.)
vendor/bin/sail up -d

# Start Vite dev server
vendor/bin/sail npm run dev

Mailpit is available at localhost:8025 for viewing emails locally.

Testing

# PHP tests (Pest)
vendor/bin/sail artisan test

# JavaScript tests (Vitest)
vendor/bin/sail npm run test

# Lint
vendor/bin/sail npm run lint
vendor/bin/sail bin pint

Auth Configuration

Feature flags and redirects are configured via environment variables in .env:

AUTH_ENABLE_REGISTRATION=true
AUTH_ENABLE_PASSWORD_RESET=true
AUTH_ENABLE_REMEMBER_ME=true
AUTH_ENABLE_EMAIL_VERIFICATION=false
AUTH_ENABLE_TWO_FACTOR=false
AUTH_REQUIRE_TWO_FACTOR=false

AUTH_REDIRECT_LOGIN=/dashboard
AUTH_REDIRECT_LOGOUT=/
AUTH_REDIRECT_REGISTER=/dashboard

When AUTH_ENABLE_EMAIL_VERIFICATION=true:

• New users receive a verification email after registration
• Unverified users are redirected to the verification page
• Social login users are auto-verified (trusted from provider)
• Social accounts can only be linked to users with verified emails

When AUTH_ENABLE_TWO_FACTOR=true, authenticated users can enroll an authenticator and manage recovery codes from /profile. Existing password and social logins are both held at the two-factor challenge until a valid TOTP or one-time recovery code is provided.

Set both AUTH_ENABLE_TWO_FACTOR=true and AUTH_REQUIRE_TWO_FACTOR=true to require every authenticated user to complete enrollment before accessing protected web pages or authenticated API endpoints. Enrollment, email verification, and logout routes remain available while setup is pending.

See config/auth-ui.php for all available options including page titles, icons, legal links, and social provider configuration.

Social Login Setup

1. Uncomment a provider in config/auth-ui.php:

'providers' => [
    'github' => [
        'label' => 'GitHub',
        'icon' => 'i-simple-icons-github',
        'enabled' => env('AUTH_GITHUB_ENABLED', false),
    ],
],

2. Add the provider credentials in config/services.php:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => env('GITHUB_REDIRECT_URI'),
],

3. Set the environment variables in .env:

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_REDIRECT_URI=${APP_URL}/auth/github/callback

Built-in providers (no extra packages needed): GitHub, Google, Facebook, X, LinkedIn, GitLab, Bitbucket, Slack.

For other providers (Discord, Apple, etc.), install the community package first:

vendor/bin/sail composer require socialiteproviders/discord

Then register the event listener as described in the Socialite Providers docs.

AI Setup

If you use an AI coding assistant, run vendor/bin/sail artisan boost:install to generate the configuration files. Otherwise, you can remove the package with vendor/bin/sail composer remove laravel/boost.