Blank Svelte Starter Kit Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

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

   • Ensure Node.js (≥16.x) and Composer are installed.
   • Run php artisan serve in a separate terminal to start the Laravel backend.

2. First Use Case: Create a Svelte Page

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

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

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

3. Key Directories to Explore

   • resources/js/Pages/ – Svelte components (Inertia pages).
   • resources/js/Layouts/ – Shared layouts (e.g., AppLayout.svelte).
   • resources/js/app.ts – Global Inertia/Svelte setup.
   • vite.config.ts – Vite configuration (frontend build tool).

Implementation Patterns

Core Workflows

1. Inertia + Svelte Routing

   • Use Laravel routes (routes/web.php) to define server-side routes, which Inertia maps to Svelte components.
   • Example:

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

     <!-- resources/js/Pages/Dashboard.svelte -->
     <script lang="ts">
       import AppLayout from '@/Layouts/AppLayout';
     </script>
     <AppLayout>
       <h1>Dashboard</h1>
     </AppLayout>
     

   • Tip: Leverage Inertia’s visit() method in Svelte for client-side navigation:

     <button on:click={() => visit('/dashboard')}>Go to Dashboard</button>
     

2. State Management

   • Use Svelte’s reactive statements or Pinia (add via npm install pinia) for frontend state.
   • Pass data from Laravel to Svelte via Inertia’s Inertia.render():

     return Inertia::render('Welcome', ['user' => auth()->user()]);
     

     <script lang="ts">
       export let user: { name: string };
     </script>
     <p>Hello, {user.name}!</p>
     

3. API Integration

   • Use Laravel’s API routes (routes/api.php) for backend endpoints.
   • Call APIs from Svelte with fetch or Axios:

     <script lang="ts">
       let posts: any[] = [];
       async function fetchPosts() {
         const response = await fetch('/api/posts');
         posts = await response.json();
       }
     </script>
     <button on:click={fetchPosts}>Load Posts</button>
     

4. Authentication (Manual Setup)

   • The starter kit lacks scaffolding, but integrate Laravel Sanctum/Passport:
     • Install Sanctum: composer require laravel/sanctum.
     • Configure Sanctum and add middleware to API routes.
     • Use Sanctum’s auth() helper in Svelte:

       <script lang="ts">
         import { auth } from '@inertiajs/inertia-svelte';
       </script>
       <p>User: {auth.user?.name}</p>
       

5. Tailwind CSS

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

     module.exports = {
       content: [
         './resources/**/*.svelte',
         './resources/**/*.ts',
       ],
     };
     

   • Use in Svelte:

     <div class="bg-blue-500 text-white p-4">Styled with Tailwind</div>
     

6. TypeScript Support

   • All .svelte files use <script lang="ts">. Define types in resources/js/types/ or globally in app.ts.

Gotchas and Tips

Pitfalls

1. Inertia Page Loading States

   • By default, Inertia shows a loading spinner during page transitions. Customize in resources/js/app.ts:

     import { InertiaProgress } from '@inertiajs/progress';
     InertiaProgress.init({ color: '#4F46E5' });
     

   • Debugging: Check browser console for Inertia errors (e.g., missing props or routes).

2. Vite HMR (Hot Module Replacement)

   • Changes to Svelte files trigger HMR automatically. For Laravel blade templates, use npm run dev and refresh manually.
   • Issue: HMR not working? Ensure vite.config.ts includes:

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

3. TypeScript Errors

   • Common causes:
     • Missing type definitions for Laravel helpers (e.g., auth()). Extend app.ts:

       declare global {
         interface Window {
           Laravel: {
             csrfToken: () => string;
           };
         }
       }
       

     • Forgetting to declare Inertia props in Svelte scripts (e.g., export let user).

4. CORS Issues

   • If calling APIs from Svelte, ensure Laravel’s CORS middleware is configured (e.g., fruitcake/laravel-cors):

     composer require fruitcake/laravel-cors
     

     Add to App\Http\Kernel.php:

     \Fruitcake\Cors\HandleCors::class,
     

5. Shared Layouts

   • Extend AppLayout.svelte for consistent headers/footers. Pass slots:

     <!-- resources/js/Layouts/AppLayout.svelte -->
     <slot />
     

   • Use in pages:

     <AppLayout>
       <h1>Page Content</h1>
     </AppLayout>
     

6. Environment Variables

   • Frontend variables (e.g., API URLs) should be in .env and accessed via import.meta.env:

     <script lang="ts">
       const apiUrl = import.meta.env.VITE_API_URL;
     </script>
     

   • Note: Prefix with VITE_ for Vite to expose them.

7. Debugging Inertia Props

   • Log props to console for debugging:

     <script lang="ts">
       export let data: any;
       console.log('Props:', data);
     </script>
     

Extension Points

1. Custom Inertia Responses

   • Extend Laravel’s Inertia::render() with middleware:

     Inertia::share(['flash' => function () { return session('flash'); }]);
     

   • Access in Svelte:

     <script lang="ts">
       export let flash: { message?: string };
     </script>
     {#if flash.message}
       <div>{flash.message}</div>
     {/if}
     

2. Svelte Stores for Global State

   • Create a global store in resources/js/stores/index.ts:

     import { writable } from 'svelte/store';
     export const theme = writable<'light' | 'dark'>('light');
     

   • Use in components:

     <script lang="ts">
       import { theme } from '@/stores';
     </script>
     <button on:click={() => theme.update(v => v === 'light' ? 'dark' : 'light')}>
       Toggle Theme
     </button>
     

3. Plugin Integration

   • Add Svelte plugins (e.g., svelte-preprocess) via vite.config.ts:

     import { svelte } from '@sveltejs/vite-plugin-svelte';
     export default defineConfig({
       plugins: [
         svelte({
           preprocess: [sass()], // Example: Add Sass support
         }),
       ],
     });
     

4. Testing

   • Use Laravel’s testing tools for backend and Inertia’s @inertiajs/svelte for frontend:

     // tests/Feature/PageTest.ts
     import { render } from '@testing-library/svelte';
     import Welcome from '@/Pages/Welcome.svelte';
     test('renders welcome page', () => {
       const { getByText } = render(Welcome, { user: { name: 'John' } });
       expect(getByText('Hello, John!')).toBeInTheDocument();
     });