hydration-performance

Measure SSR hydration timing and issues. Use when tracking hydration performance, debugging hydration mismatches, or optimizing SSR/SSG applications.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive suite of tools and patterns for measuring, debugging, and optimizing SSR hydration performance. It helps developers track key metrics like Time to Hydration (TTH) and Time to Interactive (TTI) across major frameworks like Next.js, Nuxt, and SvelteKit to ensure fast, error-free web applications and improved Core Web Vitals.

Use Cases

  • Detecting and resolving hydration mismatch errors where server-rendered HTML diverges from client-side state.
  • Measuring the impact of JavaScript execution time on Time to Interactive (TTI) in SSR and SSG environments.
  • Implementing framework-specific performance tracking for Next.js, Nuxt, Remix, and SvelteKit applications.
  • Identifying performance bottlenecks in partial hydration or 'Islands' architectures like Astro and Qwik.
  • Setting up automated monitoring for hydration duration to prevent performance regression during development.
namehydration-performance
descriptionMeasure SSR hydration timing and issues. Use when tracking hydration performance, debugging hydration mismatches, or optimizing SSR/SSG applications.
priority2

Hydration Performance

Measure the transition from server-rendered HTML to interactive client application.

What is Hydration?

Server HTML → JavaScript Load → Hydration → Interactive
              |_______________________________|
                    Hydration Timeline

Key Metrics

Metric Description Good Poor
TTH Time to Hydration <1s >3s
Hydration Duration JS execution time <200ms >1s
TTI Time to Interactive <3s >7s

Next.js Hydration Tracking

// app/providers.tsx
'use client';

import { useEffect, useRef, useState } from 'react';

export function HydrationTracker({ children }: { children: React.ReactNode }) {
  const [isHydrated, setIsHydrated] = useState(false);
  const hydrationStart = useRef<number>();

  useEffect(() => {
    // Component mounted = hydration complete
    const hydrationEnd = performance.now();
    setIsHydrated(true);

    // Get navigation timing
    const navigation = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;

    trackHydration({
      hydration_duration_ms: hydrationEnd - (hydrationStart.current || navigation.responseEnd),
      time_to_interactive_ms: hydrationEnd - navigation.fetchStart,
      dom_content_loaded_ms: navigation.domContentLoadedEventEnd - navigation.fetchStart,
      document_complete_ms: navigation.loadEventEnd - navigation.fetchStart,
    });
  }, []);

  // Mark hydration start (runs during SSR, captured in HTML)
  if (typeof window === 'undefined') {
    return children;
  }

  if (!hydrationStart.current) {
    hydrationStart.current = performance.now();
  }

  return children;
}

Nuxt Hydration Tracking

// plugins/hydration.client.ts
export default defineNuxtPlugin((nuxtApp) => {
  const hydrationStart = performance.now();

  nuxtApp.hook('app:mounted', () => {
    const hydrationEnd = performance.now();

    trackHydration({
      hydration_duration_ms: hydrationEnd - hydrationStart,
      route: useRoute().path,
    });
  });

  // Track hydration errors
  nuxtApp.hook('app:error', (error) => {
    if (error.message?.includes('hydration')) {
      trackHydrationError({
        error_message: error.message,
        route: useRoute().path,
      });
    }
  });
});

SvelteKit Hydration Tracking

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { onMount } from 'svelte';
  import { browser } from '$app/environment';
  import { page } from '$app/stores';

  let hydrationStart: number;

  if (browser) {
    hydrationStart = performance.now();
  }

  onMount(() => {
    const hydrationEnd = performance.now();

    trackHydration({
      hydration_duration_ms: hydrationEnd - hydrationStart,
      route: $page.route.id,
    });
  });
</script>

<slot />

Remix Hydration Tracking

// app/root.tsx
import { useEffect, useRef } from 'react';
import { useLocation } from '@remix-run/react';

function HydrationTracker() {
  const location = useLocation();
  const hydrationStart = useRef(performance.now());
  const hasTracked = useRef(false);

  useEffect(() => {
    if (!hasTracked.current) {
      const hydrationEnd = performance.now();

      trackHydration({
        hydration_duration_ms: hydrationEnd - hydrationStart.current,
        route: location.pathname,
      });

      hasTracked.current = true;
    }
  }, []);

  return null;
}

export default function App() {
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        <HydrationTracker />
        <Outlet />
        <Scripts />
      </body>
    </html>
  );
}

Hydration Error Tracking

// Capture hydration mismatch errors
function setupHydrationErrorTracking() {
  const originalError = console.error;

  console.error = (...args) => {
    const message = args.join(' ');

    // React hydration mismatch
    if (
      message.includes('Hydration failed') ||
      message.includes('Text content does not match') ||
      message.includes('did not match')
    ) {
      captureHydrationError({
        type: 'hydration_mismatch',
        message: message.slice(0, 500),
        route: window.location.pathname,
      });
    }

    originalError.apply(console, args);
  };
}

Partial Hydration (Islands)

For frameworks with partial hydration (Astro, Qwik):

// Astro - track island hydration
// src/components/TrackedIsland.astro
---
const componentName = Astro.props.name;
---

<div
  data-island={componentName}
  data-hydration-start={Date.now()}
>
  <slot />
</div>

<script>
  // Track when island becomes interactive
  const islands = document.querySelectorAll('[data-island]');

  islands.forEach((island) => {
    const observer = new MutationObserver(() => {
      const start = parseInt(island.dataset.hydrationStart || '0');
      const duration = Date.now() - start;

      trackIslandHydration({
        island_name: island.dataset.island,
        hydration_duration_ms: duration,
      });

      observer.disconnect();
    });

    observer.observe(island, { childList: true, subtree: true });
  });
</script>

Common Hydration Issues

Issue Cause Fix
Long hydration Large JS bundle Code split, lazy load
Mismatch errors Server/client divergence Use useEffect for client-only
Layout shift Hydration changes DOM Reserve space, skeleton
Slow TTI Blocking hydration Progressive/selective hydration

Anti-Patterns

  • Tracking before hydration (inaccurate timing)
  • Missing hydration error capture
  • Not tracking by route (aggregate hides issues)
  • Ignoring partial hydration opportunities
  • Large blocking JS causing slow hydration
  • See skills/core-web-vitals for LCP during hydration
  • See skills/bundle-performance for JS size impact
  • See skills/route-transition-tracking for navigation after hydration

References

  • references/frameworks/nextjs.md - Next.js hydration patterns
  • references/frameworks/nuxt.md - Nuxt hydration patterns
  • references/performance.md - Performance budgets