Blank React Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

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

   • Runs Vite in dev mode, compiling React + Tailwind with HMR.

2. First Use Case: Rendering a React Page

   • Create a Laravel route:

     // routes/web.php
     Route::get('/dashboard', function () {
         return Inertia::render('Dashboard');
     });
     

   • Define the React component:

     // resources/js/Pages/Dashboard.tsx
     export default function Dashboard() {
         return <h1 className="text-2xl font-bold">Welcome to Dashboard</h1>;
     }
     

   • Visit /dashboard to see the page render.

3. Key Directories to Explore

   • resources/js/Pages/ – React components (Inertia pages).
   • resources/js/Layouts/ – Shared layouts (e.g., AppLayout.tsx).
   • routes/web.php – Server-side routes mapped to React pages.
   • vite.config.ts – Vite configuration (asset handling, plugins).

Implementation Patterns

Core Workflows

1. Page-Based Routing with Inertia

   • Pattern: One Laravel route → One React component.
   • Example:

     // routes/web.php
     Route::get('/profile', [ProfileController::class, 'show']);
     

     // resources/js/Pages/Profile.tsx
     export default function Profile({ user }: { user: User }) {
         return <div>{user.name}</div>;
     }
     

   • Pros: Server-side routing, shared auth/validation logic, SEO-friendly.

2. State Management

   • Local State: Use React hooks (useState, useEffect) for component-scoped state.
   • Global State: Leverage Laravel’s session or Inertia’s usePage for shared data (e.g., auth user).

     const { auth } = usePage().props;
     

   • API Calls: Use axios (pre-configured) for backend communication.

     const response = await axios.get('/api/data');
     

3. Form Handling

   • Pattern: Use Inertia’s form handling with Laravel validation.
   • Example:

     const form = useForm({
         email: '',
     });
     form.post('/submit', {
         preserveScroll: true,
     });
     

   • Backend Validation: Laravel validates input; errors propagate to React via Inertia.

4. Layouts and Shared UI

   • Extend AppLayout for consistent headers/footers:

     export default function Dashboard() {
         return (
             <AppLayout>
                 <h1>Dashboard</h1>
             </AppLayout>
         );
     }
     

   • Tip: Use resources/js/Layouts/Guest.tsx for auth-agnostic pages.

5. API Integration

   • Sanctum/Passport: Authenticate API requests via Laravel Sanctum.

     axios.get('/api/user', {
         headers: { Authorization: `Bearer ${token}` },
     });
     

   • CSRF Protection: Inertia handles CSRF tokens automatically for form submissions.

Integration Tips

1. Tailwind CSS

   • Pre-configured for utility classes. Extend tailwind.config.js for custom themes:

     module.exports = {
         theme: {
             extend: {
                 colors: {
                     primary: '#3b82f6',
                 },
             },
         },
     };
     

2. TypeScript

   • Type-safe props via Inertia’s Page interface:

     interface Props {
         user: { name: string };
     }
     export default function Page({ user }: Props) { ... }
     

3. Environment Variables

   • Access via import.meta.env (Vite) or config() (Laravel):

     const apiUrl = import.meta.env.VITE_API_URL;
     

4. Testing

   • Frontend: Use @inertiajs/react test utilities or React Testing Library.
   • Backend: Laravel’s HttpTests for API routes.

Gotchas and Tips

Pitfalls

1. Inertia Page Mismatch

   • Issue: Route returns Inertia::render('Page') but resources/js/Pages/Page.tsx doesn’t exist.
   • Fix: Ensure React component filenames match the Inertia page name (case-sensitive).

2. Vite/HMR Delays

   • Issue: Changes in React don’t reflect immediately.
   • Fix: Restart dev server (npm run dev) or check browser console for errors.

3. CSRF Token Errors

   • Issue: Form submissions fail with 419 (CSRF mismatch).
   • Fix: Ensure {{ csrf_token() }} is in Laravel blade templates (if using traditional forms) or rely on Inertia’s automatic handling for SPA forms.

4. TypeScript Errors

   • Issue: Property 'xxx' does not exist on type 'PageProps'.
   • Fix: Extend the PageProps interface in resources/js/shims.d.ts:

     declare global {
         interface PageProps {
             user: User;
         }
     }
     

5. Asset Loading

   • Issue: CSS/JS not loading in production.
   • Fix: Run npm run build and ensure public/build assets are linked in Laravel’s app.blade.php:

     @vite(['resources/js/app.tsx', 'resources/css/app.css'])
     

Debugging Tips

1. Inertia Logs

   • Enable debug mode in config/inertia.php:

     'debug' => env('APP_DEBUG', true),
     

   • Check Laravel logs (storage/logs/laravel.log) for Inertia errors.

2. Network Tab

   • Inspect failed API calls in Chrome DevTools → Network tab for payload/response details.

3. Vite Dev Server

   • Clear cache with npm run dev -- --force.

Extension Points

1. Custom Inertia Responses

   • Override HandleInertiaRequests middleware to modify responses:

     public function share(Request $request): array
     {
         return array_merge(parent::share($request), [
             'appName' => 'MyApp',
         ]);
     }
     

2. Plugin Integration

   • Add Vite plugins in vite.config.ts:

     import laravel from 'laravel-vite-plugin';
     export default defineConfig({
         plugins: [
             laravel({
                 input: ['resources/js/app.tsx'],
                 refresh: true,
             }),
             // Add other plugins (e.g., @vitejs/plugin-react)
         ],
     });
     

3. Authentication

   • Integrate Laravel Fortify/Breeze with Inertia:

     composer require laravel/fortify
     php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"
     

   • Use Inertia::auth() in middleware and usePage().props.auth in React.

4. Internationalization (i18n)

   • Use laravel-lang or vue-i18n with Inertia:

     import { usePage } from '@inertiajs/react';
     const { __ } = usePage().props;