Vue Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

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

   • The starter kit includes Vite, Vue 3, TypeScript, and Tailwind CSS preconfigured.
   • Runs on http://localhost:8000 by default.

2. First Use Case: Create a Page

   • Generate a new Inertia page:

     php artisan inertia:page Dashboard
     

   • This creates:
     • A Vue component (resources/js/Pages/Dashboard.vue)
     • A controller (app/Http/Controllers/DashboardController.php)
     • A route (routes/web.php)

3. Where to Look First

   • resources/js/: Vue/TypeScript frontend entry point.
   • resources/js/Pages/: Inertia page components.
   • resources/js/Layouts/: Shared layouts (e.g., AuthenticatedLayout.vue).
   • resources/views/app.blade.php: Root Blade template (renders Vue app).
   • vite.config.ts: Vite configuration (optimizations, plugins).

Implementation Patterns

Core Workflows

1. Inertia + Laravel Routing

   • Use Laravel’s Route::inertia() for server-side routing:

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

   • Pass data from controllers to Vue:

     public function index()
     {
         return Inertia::render('Dashboard', [
             'users' => User::all(),
         ]);
     }
     

   • Access props in Vue:

     <script setup>
     defineProps<{
         users: User[];
     }>();
     </script>
     

2. Component-Based Development

   • Shared Components: Place reusable UI (e.g., buttons, modals) in resources/js/Components/.
   • Layouts: Extend AuthenticatedLayout.vue for auth-protected pages.
   • Composition API: Prefer <script setup> for cleaner code:

     <script setup>
     import { ref } from 'vue';
     const count = ref(0);
     </script>
     

3. State Management

   • Pinia is included by default. Create a store:

     php artisan inertia:pinia Auth
     

   • Use in components:

     import { useAuthStore } from '@/Stores/Auth';
     const auth = useAuthStore();
     

4. API Calls

   • Use Laravel’s axios wrapper (resources/js/bootstrap.ts):

     import { router } from '@inertiajs/vue3';
     await router.post('/logout');
     

   • Or direct Axios calls:

     import axios from '@/Axios';
     const response = await axios.get('/api/users');
     

5. Tailwind + shadcn-vue

   • Install shadcn components:

     npx shadcn-vue@latest add button
     

   • Use pre-styled components:

     <Button>Click Me</Button>
     

6. Testing

   • Frontend: Use Vitest (npm run test).
   • Backend: Laravel’s Pest (php artisan test).

Gotchas and Tips

Pitfalls

1. Inertia Page Caching

   • Clear Vite cache after adding new Inertia pages:

     npm run dev -- --force
     

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

     server: { hmr: { host: 'localhost' } }
     

2. TypeScript Strictness

   • Ensure tsconfig.json is configured for Vue 3:

     {
       "compilerOptions": {
         "types": ["vite/client"]
       }
     }
     

   • Add types for Inertia props:

     interface PageProps {
         flash: { type: string; message: string };
     }
     

3. shadcn-vue Component Conflicts

   • Avoid naming conflicts with Laravel Blade components (e.g., resources/views/components/).
   • Prefix shadcn components or use a separate directory.

4. CSRF Token in API Calls

   • Include @csrf in forms or use axios with Laravel’s CSRF cookie:

     axios.defaults.withCredentials = true;
     

5. Vite HMR Issues

   • If HMR stops working, restart the dev server or check vite.config.ts for misconfigured plugins.

Debugging Tips

1. Inertia Page Errors

   • Check browser console for Vue errors.
   • Verify the controller returns Inertia::render() with correct props.

2. TypeScript Errors

   • Run npm run dev with --debug for detailed TS errors.
   • Extend global types in resources/js/shims-vue.d.ts:

     declare module '@inertiajs/vue3' {
       namespace Inertia {
         interface PageProps {}
       }
     }
     

3. Tailwind JIT Issues

   • Ensure tailwind.config.js includes all necessary paths:

     content: [
       './resources/**/*.blade.php',
       './resources/js/**/*.{vue,ts}',
     ],
     

Extension Points

1. Custom Vite Plugins

   • Add plugins in vite.config.ts:

     import laravel from 'laravel-vite-plugin';
     export default defineConfig({
       plugins: [
         laravel({
           input: ['resources/js/app.ts'],
           refresh: true,
         }),
         // Add custom plugins here
       ],
     });
     

2. Middleware for Inertia

   • Use Laravel middleware to modify Inertia responses:

     public function handle($request, Closure $next)
     {
         $response = $next($request);
         if ($response->isInertia()) {
             $response->withProps(['theme' => 'dark']);
         }
         return $response;
     }
     

3. Custom Inertia Layouts

   • Override the default layout in app/Http/Middleware/HandleInertiaRequests.php:

     public function rootView(): string
     {
         return file_exists(resource_path('js/Pages/app.blade.php'))
             ? 'app'
             : false;
     }
     

4. Environment-Specific Config

   • Use .env variables to toggle features (e.g., debug mode):

     // vite.config.ts
     const isDebug = process.env.NODE_ENV === 'debug';