How to Fix SvelteKit v5.0 SSR Hydration Errors (I Spent 2 Days So You Don't Have To)

// This worked perfectly in v4, breaks everything in v5
<script>
  import { browser } from '$app/environment';
  
  let currentTime = new Date().toISOString();
  
  // The hydration killer - different values on server vs client
  if (browser) {
    currentTime = new Date().toISOString(); // Different timestamp!
  }
</script>

<p>Current time: {currentTime}</p>

// Looks harmless, causes hydration chaos
<script>
  import { browser } from '$app/environment';
  
  let userPreferences = null;
  
  onMount(() => {
    userPreferences = JSON.parse(localStorage.getItem('prefs'));
  });
</script>

{#if userPreferences}
  <UserSettings {userPreferences} />
{:else}
  <DefaultSettings />
{/if}

// HydrationSafeStore.js - My secret weapon
import { writable } from 'svelte/store';
import { browser } from '$app/environment';

export function createHydrationSafeStore(key, defaultValue, options = {}) {
  const { serialize = JSON.stringify, deserialize = JSON.parse } = options;
  
  // Always start with the default value during SSR
  const store = writable(defaultValue);
  
  // Only hydrate from storage AFTER mount
  if (browser) {
    const stored = localStorage.getItem(key);
    if (stored) {
      try {
        store.set(deserialize(stored));
      } catch (e) {
        console.warn(`Failed to deserialize ${key}:`, e);
        // Keep the default value
      }
    }
    
    // Auto-persist changes
    store.subscribe(value => {
      localStorage.setItem(key, serialize(value));
    });
  }
  
  return store;
}

<script>
  import { createHydrationSafeStore } from './HydrationSafeStore.js';
  
  // This pattern has saved me countless hours
  const userPreferences = createHydrationSafeStore('user-prefs', {
    theme: 'light',
    notifications: true
  });
</script>

<!-- Server and client always start with the same state -->
<UserInterface preferences={$userPreferences} />

<script>
  import { onMount } from 'svelte';
  
  let mounted = false;
  let clientOnlyData = null;
  
  onMount(() => {
    // This ensures server and initial client render are identical
    mounted = true;
    
    // Now safely load client-specific data
    clientOnlyData = detectUserAgent();
    
    return () => {
      mounted = false;
    };
  });
</script>

<!-- Server renders nothing, client renders after mount -->
{#if mounted && clientOnlyData}
  <ClientSpecificComponent data={clientOnlyData} />
{:else}
  <div style="height: 200px;">
    <!-- Prevent layout shift with placeholder -->
    <LoadingSpinner />
  </div>
{/if}

<script>
  import { page } from '$app/stores';
  import { onMount } from 'svelte';
  
  // Start with server-safe defaults
  let userSettings = {
    theme: 'system',
    language: 'en',
    timezone: 'UTC'
  };
  
  let isHydrated = false;
  
  onMount(() => {
    // Mark as hydrated first
    isHydrated = true;
    
    // Then safely update with client data
    const stored = localStorage.getItem('user-settings');
    if (stored) {
      userSettings = { ...userSettings, ...JSON.parse(stored) };
    }
  });
</script>

<!-- Always renders the same structure -->
<div class="user-dashboard" data-hydrated={isHydrated}>
  <ThemeSelector bind:value={userSettings.theme} />
  <LanguagePicker bind:value={userSettings.language} />
  <TimezonePicker bind:value={userSettings.timezone} />
</div>

<style>
  /* Smooth transition after hydration */
  .user-dashboard:not([data-hydrated="true"]) .client-only-feature {
    opacity: 0.5;
    pointer-events: none;
  }
</style>

// ForceClientRender.svelte - Use sparingly!
<script>
  import { browser } from '$app/environment';
  import { onMount } from 'svelte';
  
  let forceRender = false;
  
  onMount(() => {
    // Force a re-render after hydration
    forceRender = true;
  });
</script>

{#if !browser || !forceRender}
  <!-- Server-safe fallback -->
  <slot name="fallback">
    <div>Loading...</div>
  </slot>
{:else}
  <!-- Client-only rendering -->
  <slot />
{/if}

<ForceClientRender>
  <ProblematicComponent />
  
  <div slot="fallback">
    <SkeletonLoader />
  </div>
</ForceClientRender>

// vite.config.js
export default {
  define: {
    __SVELTEKIT_DEBUG__: true
  },
  server: {
    fs: {
      allow: ['..']
    }
  }
};

// DebugHydration.svelte
<script>
  import { browser } from '$app/environment';
  import { onMount } from 'svelte';
  
  export let label = 'Unknown';
  export let data = {};
  
  let renderPhase = browser ? 'client-initial' : 'server';
  
  onMount(() => {
    renderPhase = 'client-hydrated';
    console.log(`[${label}] Hydration complete:`, data);
  });
  
  $: {
    console.log(`[${label}] ${renderPhase}:`, data);
  }
</script>

<div class="debug-info">
  <strong>{label}</strong>: {renderPhase}
  <pre>{JSON.stringify(data, null, 2)}</pre>
</div>

<!-- Start with this minimal test -->
<script>
  let testValue = 'consistent-value';
</script>

<div>Test: {testValue}</div>

<!-- Gradually add complexity until hydration breaks -->
<!-- This pinpoints the exact problematic code -->