Svelte Starter Kit Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   • The kit auto-configures Laravel, Vite, Inertia, Svelte 5, and TypeScript. No manual vite.config.js or inertia.config.js tweaks are needed for basic use.

2. First Use Case:

   • Navigate to /resources/js/Pages/Welcome.svelte and modify the <h1> tag to test reactivity.
   • Run php artisan serve and visit http://localhost:8000. Changes reflect instantly due to Vite’s HMR.

3. Key Directories:

   • Frontend: resources/js/Pages/ (Svelte components), resources/js/Layouts/ (shared layouts).
   • Backend: app/Http/Controllers/ (Inertia controllers), routes/web.php (server-side routes).
   • Config: vite.config.ts (Vite settings), inertia.config.ts (Inertia presets).

Implementation Patterns

Core Workflow: Inertia + Svelte

1. Server-Side Routing:

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

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

   • No client-side routing libraries (e.g., React Router) needed—Laravel handles history API under the hood.

2. Data Fetching:

   • Pass data from controllers to Svelte via Inertia::render():

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

   • Access in Svelte:

     <script lang="ts">
         export let users: User[];
     </script>
     

3. State Management:

   • Local State: Use Svelte’s reactive stores (import { writable } from 'svelte/store').
   • Global State: Leverage Laravel’s session or Inertia’s page.props for shared data (e.g., auth user):

     <script lang="ts">
         import { page } from '@inertiajs/svelte';
     </script>
     <p>Welcome, {page.props.auth.user.name}</p>
     

4. Forms:

   • Use useForm from @inertiajs/svelte for CSRF protection and server-side validation:

     <script lang="ts">
         import { useForm } from '@inertiajs/svelte';
         const form = useForm({
             email: '',
             password: '',
         });
     </script>
     <form method="POST" on:submit|preventDefault={form.submit('login')}>
         <input type="email" bind:value={form.data.email} />
     </form>
     

5. Component Libraries:

   • shadcn-svelte: Add components via CLI (e.g., npx shadcn-svelte@latest add button).
   • bits-ui: Import pre-built primitives (e.g., <Dropdown />) directly in Svelte files.

6. API Calls:

   • Use axios (included) with Inertia’s visit for SPA-like navigation:

     <script lang="ts">
         import { router } from '@inertiajs/svelte';
         async function fetchData() {
             const response = await axios.get('/api/data');
             router.visit('/dashboard', { data: response.data });
         }
     </script>
     

7. Authentication:

   • Pre-configured with Laravel Breeze/Inertia. Extend app/Http/Middleware/HandleInertiaRequests.php to customize share props (e.g., auth user).

Gotchas and Tips

Pitfalls

1. TypeScript Strictness:

   • The kit enforces strict TypeScript. Common issues:
     • Missing export let for props in Svelte components.
     • Incorrect type annotations for page.props (e.g., page.props.auth should be typed as Auth).
   • Fix: Run npm run typecheck to catch errors early.

2. Vite HMR Delays:

   • Large Svelte stores or complex components may cause HMR lag. Split stores into smaller files or use +page.svelte for lazy-loaded routes.

3. Inertia Page Loading:

   • Avoid heavy computations in onMount of root layouts. Use page.props for initial data and lazy-load additional content.

4. shadcn-svelte Quirks:

   • Components require explicit imports (e.g., import { Button } from '@/components/ui/button').
   • Tip: Add @/components/ui to tsconfig.json paths for cleaner imports.

5. Tailwind JIT Conflicts:

   • Custom Tailwind configs in tailwind.config.js may break if not merged properly. Use @tailwindcss/forms for default styles.

6. CSRF Token:

   • Forgetting @csrf directive in forms causes 419 errors. Use useForm or @inertiajs/svelte helpers to auto-include it.

Debugging

1. Inertia Errors:

   • Check browser console for Inertia errors. Common causes:
     • Mismatched route names between routes/web.php and Svelte’s Link components.
     • Missing method in form submissions (e.g., form.submit('POST', '/route')).

2. Vite Dev Server:

   • If Vite fails to compile, delete node_modules/.vite and restart npm run dev.

3. Laravel Logs:

   • Enable APP_DEBUG=true in .env for detailed error messages.

Extension Points

1. Custom Inertia Layouts:

   • Extend resources/js/Layouts/AppLayout.svelte for shared headers/footers. Override in child components:

     <AppLayout title="Custom Title">
         <slot />
     </AppLayout>
     

2. API Routes:

   • Use Route::prefix('api')->middleware('auth:sanctum') in routes/api.php for SPAs. Protect Svelte routes with middleware('auth').

3. Testing:

   • Use @inertiajs/svelte/testing for component tests:

     import { render } from '@testing-library/svelte';
     import { screen } from '@testing-library/svelte';
     render(<Welcome />);
     expect(screen.getByText('Welcome')).toBeInTheDocument();
     

4. Production Builds:

   • Run npm run build to generate optimized assets in public/build. Configure Laravel’s mix-manifest.json for asset versioning:

     // app/Http/Middleware/TrustProxies.php
     $app->use(TrustProxies::class)->only('web');
     

5. Monorepo Support:

   • For large apps, split Svelte into a separate repo and use npm link or Vite’s build.rollupOptions.input for modular imports.

Pro Tips

• Atomic Design: Organize Svelte components by feature (e.g., resources/js/features/Auth/Login.svelte).
• Zod Validation: Pair with zod for runtime validation in Svelte:

  <script lang="ts">
      import { z } from 'zod';
      const schema = z.object({ email: z.string().email() });
      const form = useForm({ email: '' }, { schema });
  </script>
  

• Server-Side Rendering (SSR): Enable in inertia.config.ts for SEO-critical pages:

  export default defineInertiaConfig({
      serverSideRendering: true,
  });
  

• Dark Mode: Use bits-ui’s <Theme> component or Tailwind’s dark: classes with data-theme attributes.