React Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer create-project laravel/react-starter-kit my-app
   cd my-app
   npm install
   npm run dev
   php artisan serve
   

   • The starter kit auto-configures Vite for React, Tailwind, and shadcn/ui.

2. First Use Case: Create a React Page

   • Generate a new Inertia page via Artisan:

     php artisan inertia:page Dashboard
     

   • Edit resources/js/Pages/Dashboard.tsx and its corresponding controller (app/Http/Controllers/DashboardController.php).

3. Key Directories to Explore

   • resources/js/ – React/TypeScript/Vite entry point.
   • resources/js/Pages/ – Inertia page components.
   • resources/views/app.blade.php – Root Blade template (handles Inertia’s <app> tag).
   • vite.config.ts – Vite configuration (optimizations, plugins).

Implementation Patterns

Core Workflows

1. Server-Side Routing with React

   • Define routes in routes/web.php using Inertia::render():

     Route::get('/dashboard', [DashboardController::class, 'index']);
     

   • React components receive props from Laravel controllers via Inertia’s page props:

     // Dashboard.tsx
     const { user } = props;
     

2. State Management

   • Use React Context for global state (e.g., auth) or Zustand (pre-configured in the kit).
   • Example with Zustand:

     // stores/auth.ts
     import { create } from 'zustand';
     type AuthState = { user: User | null };
     export const useAuthStore = create<AuthState>((set) => ({ user: null }));
     

   • Access in components:

     const user = useAuthStore((state) => state.user);
     

3. API Calls

   • Leverage Laravel’s Sanctum/Passport for auth + Axios (pre-configured in resources/js/api.ts):

     // Example: Fetch user data
     const response = await api.get('/api/user');
     

4. shadcn/ui Integration

   • Add components via CLI:

     npx shadcn-ui@latest add button
     

   • Components auto-import (configured in tsconfig.json via paths).

5. Tailwind Utilities

   • Use arbitrary values or JIT mode (enabled by default). Example:

     <div className="bg-blue-500 hover:bg-blue-600 transition-colors">
       Hover me
     </div>
     

6. Form Handling

   • Use React Hook Form (pre-configured) with shadcn/ui inputs:

     import { useForm } from 'react-hook-form';
     const { register, handleSubmit } = useForm();
     

7. Testing

   • Frontend: Jest + Testing Library (pre-configured in resources/js/tests/).
   • Backend: Laravel’s Pest (configured in phpunit.xml).

Integration Tips

• Laravel Mix Replacement: Vite replaces Laravel Mix. Use npm run dev/build instead of mix.
• Hot Module Replacement (HMR): Edit React files and see changes instantly (no full page reload).
• TypeScript: All React components are TypeScript-first. Extend PageProps for custom props:

  interface DashboardProps extends PageProps {
    stats: { users: number; posts: number };
  }
  

• Environment Variables: Use .env for both Laravel and Vite (prefix with VITE_ for client-side access):

  VITE_APP_API_URL=/api
  

  Access in React:

  const apiUrl = import.meta.env.VITE_APP_API_URL;
  

Gotchas and Tips

Pitfalls

1. Inertia Page Caching

   • Clear Vite cache after changing Inertia page routes:

     npm run build
     

   • Or disable caching during development in vite.config.ts:

     server: { hmr: { clientPort: 2999 } },
     

2. TypeScript Errors

   • Ensure resources/js/shims-vite.d.ts includes all global types (e.g., import.meta.env).
   • Rebuild after adding new shadcn/ui components:

     npx shadcn-ui@latest add [component]
     

3. CSRF Token Mismatch

   • If using Laravel’s csrf-token meta tag, ensure it’s included in resources/views/app.blade.php:

     @csrf
     <meta name="csrf-token" content="{{ csrf_token() }}">
     

4. Vite Public Assets

   • Place static assets (e.g., images) in public/ and reference them via:

     <img src="/images/logo.png" alt="Logo" />
     

5. Zustand Persistence

   • Store Zustand state in localStorage manually if needed:

     const useAuthStore = create<AuthState>()((set) => ({
       user: JSON.parse(localStorage.getItem('user') || 'null'),
     }));
     

Debugging

• Inertia Errors: Check browser console for Inertia warnings (e.g., missing page components).
• Vite Dev Server: Access logs at http://localhost:5173 (default Vite port).
• Laravel Logs: Tail logs with:

  tail -f storage/logs/laravel.log
  

Extension Points

1. Custom Vite Plugins Add plugins in vite.config.ts:

   import { defineConfig } from 'vite';
   import laravel from 'laravel-vite-plugin';
   import { VitePWA } from 'vite-plugin-pwa';
   
   export default defineConfig({
     plugins: [
       laravel({ input: ['resources/js/app.tsx'], refresh: true }),
       VitePWA({ strategies: 'injectManifest' }),
     ],
   });
   

2. Laravel Service Providers Extend AppServiceProvider for global React props:

   public function boot()
   {
       Inertia::share([
           'auth' => fn () => auth()->user(),
           'settings' => config('app.settings'),
       ]);
   }
   

3. Tailwind Customization Modify tailwind.config.js:

   module.exports = {
     content: [
       './resources/js/**/*.{ts,tsx}',
       './resources/views/**/*.blade.php',
     ],
     theme: {
       extend: {
         colors: {
           primary: '#3b82f6',
         },
       },
     },
   };
   

4. React Router Integration Use react-router-dom alongside Inertia for client-side navigation (advanced):

   import { BrowserRouter, Routes, Route } from 'react-router-dom';
   // Wrap app in resources/js/app.tsx
   

5. Monorepo Support For large projects, eject Vite config and use pnpm/yarn workspaces to share dependencies between Laravel and React.