Blank Vue Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

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

   • Ensure php, composer, and node are installed.
   • Run php artisan serve in a separate terminal to start the Laravel backend.

2. First Use Case: Create a Vue Page

   • Navigate to resources/js/Pages/ and create a new Vue component (e.g., Welcome.vue).
   • Define a route in routes/web.php:

     Route::get('/', function () {
         return Inertia::render('Welcome');
     });
     

   • Access http://localhost:8000 to see your new page.

3. Key Directories to Explore

   • resources/js/Pages/ – Vue components tied to Laravel routes.
   • resources/js/Layouts/ – Shared layouts (e.g., AppLayout.vue).
   • resources/js/Composables/ – Reusable logic (e.g., useForm, usePage).
   • vite.config.js – Vite configuration for asset handling.

Implementation Patterns

Core Workflow: Inertia + Vue Integration

1. Server-Side Routing with Vue

   • Use Laravel routes (routes/web.php) to map to Vue components via Inertia::render().
   • Example:

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

     <!-- resources/js/Pages/Dashboard.vue -->
     <template>
         <AppLayout>
             <h1>Dashboard</h1>
         </AppLayout>
     </template>
     

2. State Management

   • Leverage Inertia’s usePage composable to access Laravel data:

     <script setup>
     import { usePage } from '@inertiajs/vue3';
     const props = defineProps({
         // Access via `usePage().props`
     });
     </script>
     

   • Use Pinia (included) for client-side state:

     npm install pinia
     

     Configure in resources/js/app.ts:

     import { createPinia } from 'pinia';
     app.use(createPinia());
     

3. API Calls with useForm

   • Submit forms or fetch data without full page reloads:

     <script setup>
     import { useForm } from '@inertiajs/vue3';
     const form = useForm({
         name: '',
     });
     const submit = () => form.post('/submit');
     </script>
     

4. Tailwind CSS

   • Preconfigured for utility-first styling. Extend in tailwind.config.js:

     module.exports = {
         content: [
             './resources/**/*.blade.php',
             './resources/**/*.vue',
         ],
     };
     

5. TypeScript Support

   • All .vue files default to TypeScript. Define props/interfaces:

     <script setup lang="ts">
     interface Props {
         title: string;
     }
     defineProps<Props>();
     </script>
     

Gotchas and Tips

Pitfalls

1. Inertia Page Loading

   • Issue: Pages flash briefly before Vue hydrates.
   • Fix: Use inertia:before or inertia:progress events in AppLayout.vue:

     <template>
         <div @inertia:before="startLoading" @inertia:progress="updateProgress">
             <!-- Content -->
         </div>
     </template>
     <script setup>
     import { ref } from 'vue';
     const progress = ref(0);
     const startLoading = () => { progress.value = 0; };
     const updateProgress = (e: { progress: number }) => { progress.value = e.progress; };
     </script>
     

2. Vite HMR (Hot Module Replacement)

   • Issue: Changes in .vue files may not reflect immediately.
   • Fix: Ensure npm run dev is running and check browser console for errors. Restart Vite if needed:

     npm run dev -- --force
     

3. TypeScript Errors

   • Issue: Missing types for Inertia/Pinia.
   • Fix: Install types explicitly:

     npm install --save-dev @types/inertia @pinia/testing
     

4. Shared Layouts

   • Issue: Nested layouts may break Inertia’s page resolution.
   • Fix: Ensure AppLayout.vue wraps only the <slot>:

     <template>
         <div>
             <header>...</header>
             <main>
                 <slot /> <!-- Only child content -->
             </main>
         </div>
     </template>
     

Debugging Tips

1. Inertia Visits

   • Log page visits in resources/js/app.ts:

     import { router } from '@inertiajs/vue3';
     router.on('navigate', () => console.log('Page changed'));
     

2. Laravel + Vue Dev Tools

   • Install browser extensions:
     • Laravel Debugbar
     • Vue DevTools

3. Environment-Specific Config

   • Use .env variables for API endpoints or feature flags:

     VITE_APP_API_URL=https://api.example.com
     

   • Access in Vue:

     const apiUrl = import.meta.env.VITE_APP_API_URL;
     

Extension Points

1. Custom Inertia Plugins

   • Extend Inertia’s behavior in resources/js/app.ts:

     import { plugin } from '@inertiajs/vue3';
     app.use(plugin, {
         resolve: (name) => require(`./Pages/${name}.vue`),
         page: { component: 'AppLayout' },
     });
     

2. API Middleware

   • Add middleware to resources/js/app.ts for global API calls:

     app.config.globalProperties.$api = {
         get: (url: string) => axios.get(url),
         post: (url: string, data: any) => axios.post(url, data),
     };
     

3. Testing

   • Use Inertia’s testing helpers in tests/Feature:

     use Inertia\Testing\Assert;
     $response = $this->get('/dashboard');
     $response->assertInertia(fn (Assert $page) =>
         $page->component('Dashboard')
     );
     

4. Multi-Page Apps (MPA) Fallback

   • Disable Inertia for specific routes by returning Blade views:

     Route::get('/legacy', function () {
         return view('legacy.page');
     })->middleware('disable.inertia');