WorkOS

Overview: Why Modern Starter Kits Matter Building a robust authentication system from scratch is a repetitive, error-prone task that can stall the momentum of a new project. Laravel has long solved this with Breeze and Jetstream, but the latest evolution of Laravel Starter Kits shifts the focus toward modern UI aesthetics and developer experience. These kits aren't just boilerplate; they are a curated selection of industry-best tools like Tailwind CSS V4 and Shadcn UI, providing a professional-grade foundation for SaaS applications. By leveraging these kits, you bypass the hours spent configuring build tools, setting up dark mode, and designing responsive sidebars. Instead, you start with a fully functional, high-fidelity dashboard that is ready for production. This tutorial explores the React and Livewire flavors of these kits, demonstrating how to install, customize, and extend them to fit your specific application needs. Prerequisites To follow along with this guide, you should have a baseline understanding of the following: * **PHP & Laravel:** Basic familiarity with the Laravel framework, including Eloquent models and routing. * **Terminal Usage:** Comfort using the command line to run `composer` and `php artisan` commands. * **Local Development Environment:** Tools like Laravel Herd or Valet to serve your local `.test` sites. * **Frontend Basics:** A working knowledge of either React (for the Inertia kit) or Blade templates (for the Livewire kit). Key Libraries & Tools Before we dive into the code, let's identify the heavy lifters in these new kits: * **Laravel Starter Kits:** The official scaffolding packages for rapid application setup. * **Shadcn UI:** A collection of re-usable components built using Radix UI and Tailwind CSS. Unlike a traditional library, these are copied directly into your project for total control. * **Tailwind CSS V4:** The newest version of the utility-first CSS framework, featuring improved performance and a simplified configuration process. * **Inertia.js V2:** The bridge between Laravel and modern frontend frameworks like React or Vue. * **Livewire & Volt:** A full-stack framework for Laravel that allows you to build dynamic interfaces using PHP. Volt adds an elegant, single-file functional API to Livewire. * **Pest:** A delightful PHP testing framework focused on simplicity and readability. Code Walkthrough: Installing and Customizing React The React starter kit uses Inertia.js to deliver a seamless single-page application (SPA) experience. Let's look at the installation process and how to toggle between different visual layouts. 1. Installation Start by using the Laravel installer to create a new project. You will be prompted to choose your stack. Select React and choose the built-in Laravel authentication unless you specifically need WorkOS integration. ```bash Create a new React project laravel new react-app ``` During installation, you can opt for Pest as your testing framework. The installer uses a "drift" plugin to automatically convert standard PHPUnit tests into the Pest syntax, ensuring your test suite is modern from day one. 2. Switching Layouts in React The new kits include multiple authentication layouts: `Simple`, `Card`, and `Split`. To change the appearance of your login or registration pages, you only need to modify a single import in the Inertia layout file. Navigate to `resources/js/layouts/auth-layout.tsx` (or the equivalent `.js` file). You can swap the layout component being used: ```javascript // resources/js/layouts/auth-layout.tsx // To change to a split layout with a quote and image on the left: import { AuthSplitLayout } from '@/layouts/auth/auth-split-layout'; export default function AuthLayout({ children }) { return <AuthSplitLayout children={children} />; } ``` 3. Adding Shadcn Components Because Shadcn UI components are just files in your `resources` directory, adding new ones is a matter of running an `npx` command. For instance, to add a toggle switch to your dashboard: ```bash npx shadcn-ui@latest add switch ``` Then, import it directly into your dashboard page: ```javascript // resources/js/pages/dashboard.tsx import { Switch } from "@/components/ui/switch"; export default function Dashboard() { return ( <div> <h1>Dashboard</h1> <Switch /> </div> ); } ``` Deep Dive: Livewire, Volt, and Functional PHP If you prefer staying within the PHP ecosystem while maintaining a dynamic frontend, the Livewire kit is the primary choice. This kit heavily utilizes Volt, which allows you to define your component logic and Blade template in the same file. 1. Creating a Volt Component A Volt component represents a modern way to handle state in Laravel. Instead of having a separate Class file and Blade file, everything is co-located. ```bash php artisan make:volt counter ``` This creates a file at `resources/views/livewire/counter.blade.php`. Here is how you write a functional counter using the Volt API: ```php <?php use function Livewire\Volt\{state}; state(['count' => 0]); $increment = fn () => $this->count++; ?> <div> <h1>{{ $count }}</h1> <button wire:click="increment">+</button> </div> ``` 2. Livewire Routing Livewire components can be served as full-page components. In your `routes/web.php`, you can map a URL directly to a Volt component without needing a controller: ```php use Livewire\Volt\Volt; Volt::route('/counter', 'counter'); ``` This approach dramatically reduces the "boilerplate" code required to get a functional page onto the screen. Syntax Notes * **Class Names:** In React components, remember to use `className` instead of `class`. When working with the Split Layout, ensure your text colors (like `text-white`) are applied to visible containers, or they may be obscured by background divs. * **Middleware:** The kits come with `password.confirm` middleware pre-configured. Applying this to a route forces the user to re-enter their password before viewing sensitive settings. * **Email Verification:** To enable mandatory email verification, simply ensure your `User` model implements the `MustVerifyEmail` contract and uncomment the relevant line in your model file. Practical Examples * **SaaS Dashboard:** Use the `SidebarLayout` as the foundation for a multi-tenant dashboard. Since the sidebar is fully customizable, you can easily add dynamic menu items based on the user's subscription tier. * **Marketing Pages:** The `AuthSplitLayout` is perfect for modern landing pages where you want a high-resolution brand image or customer testimonial to sit alongside the sign-up form. * **Internal Tools:** Use the Livewire kit with Shadcn equivalents to build rapid CRUD interfaces. The ability to keep logic and views in a single Volt file makes maintaining dozens of internal forms much easier. Tips & Gotchas * **Asset Watcher:** Always keep `npm run dev` or `vite` running in the background. If your layout changes aren't appearing, it's likely because the asset watcher isn't picking up your file saves. * **Shadcn Portability:** Remember that Shadcn UI isn't a package you update via `composer` or `npm`. If you want the latest version of a component, you generally re-run the `add` command and overwrite the existing file. * **Vue Compatibility:** If you choose the Vue starter kit, be aware that as of early 2025, some Shadcn Vue components may still be catching up to Tailwind CSS V4. Check the official documentation for the latest compatibility patches. * **Testing:** Use Pest to verify your customizations. If you delete a component you think is unused, run `vendor/bin/pest` to ensure you haven't broken a dependency in the authentication flow.