Debugging SvelteKit 5 SSR Problems with AI: A Complete Tutorial

<!-- AI detects and fixes hydration issues -->

<!-- ❌ Problematic component causing hydration mismatch -->
<script>
  import { browser } from '$app/environment';
  
  // AI detects: Date/time inconsistency between server and client
  let currentTime = new Date().toISOString();
  
  // AI detects: Browser-only API usage
  let userAgent = navigator.userAgent; // Error: navigator not available on server
</script>

<div>
  <p>Current time: {currentTime}</p>
  <p>User agent: {userAgent}</p>
</div>

<!-- ✅ AI-fixed solution -->
<script>
  import { browser } from '$app/environment';
  import { onMount } from 'svelte';
  
  let currentTime = '';
  let userAgent = '';
  
  // AI suggests: Client-only hydration for dynamic content
  onMount(() => {
    currentTime = new Date().toISOString();
    userAgent = navigator.userAgent;
  });
</script>

<div>
  {#if currentTime}
    <p>Current time: {currentTime}</p>
  {/if}
  {#if userAgent}
    <p>User agent: {userAgent}</p>
  {/if}
</div>

// AI optimizes SSR state management

// ❌ Problematic store causing SSR issues
import { writable } from 'svelte/store';

// AI detects: Store initialized with browser-only values
export const userStore = writable({
  theme: localStorage.getItem('theme') || 'dark', // Error on server
  sessionId: crypto.randomUUID() // Different values server/client
});

// ✅ AI-optimized SSR-safe store
import { writable } from 'svelte/store';
import { browser } from '$app/environment';

// AI suggests: SSR-safe initialization
function createUserStore() {
  const initialState = {
    theme: 'dark', // Safe default
    sessionId: null
  };
  
  const { subscribe, set, update } = writable(initialState);
  
  return {
    subscribe,
    set,
    update,
    // AI suggests: Client-only initialization method
    initializeClient: () => {
      if (browser) {
        update(state => ({
          ...state,
          theme: localStorage.getItem('theme') || 'dark',
          sessionId: crypto.randomUUID()
        }));
      }
    }
  };
}

export const userStore = createUserStore();

// AI generates robust SSR load functions

// ❌ Problematic load function
export async function load({ params, fetch }) {
  // AI detects: No error handling for SSR failures
  const response = await fetch(`/api/posts/${params.id}`);
  const post = await response.json();
  
  // AI detects: Missing fallback for server failures
  return {
    post
  };
}

// ✅ AI-optimized load function
export async function load({ params, fetch, url }) {
  try {
    // AI suggests: Timeout and error handling
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 5000);
    
    const response = await fetch(`/api/posts/${params.id}`, {
      signal: controller.signal
    });
    
    clearTimeout(timeoutId);
    
    if (!response.ok) {
      // AI suggests: Proper error status handling
      if (response.status === 404) {
        throw error(404, 'Post not found');
      }
      throw error(500, 'Failed to load post');
    }
    
    const post = await response.json();
    
    // AI suggests: Data validation
    if (!post.id || !post.title) {
      throw error(500, 'Invalid post data');
    }
    
    return {
      post,
      // AI suggests: Include metadata for client
      meta: {
        loadedAt: new Date().toISOString(),
        source: 'ssr'
      }
    };
    
  } catch (err) {
    // AI suggests: Graceful fallback handling
    if (err.name === 'AbortError') {
      throw error(408, 'Request timeout');
    }
    
    console.error('Load function error:', err);
    
    // AI suggests: Fallback data structure
    return {
      post: null,
      error: 'Failed to load post',
      meta: {
        loadedAt: new Date().toISOString(),
        source: 'fallback'
      }
    };
  }
}