Implementing Partial Hydration for web application optimization
Full Hydration — browser loads entire JS bundle and hydrates entire DOM, including components that never become interactive. Static header, article list, footer — all hydrated. Direct losses: extra JS, extra CPU, slow TTI.
Partial Hydration — hydrate only components that need it. Static content remains inert HTML. JS loads only for interactive islands.
Full Hydration problem
Typical blog page:
- Header (static) → hydrate? Why?
- Navigation (static) → hydrate? Why?
- ArticleContent (MDX) → hydrate? Why?
- Comments (interactive) → NEED hydration
- ShareButtons (onClick) → NEED hydration
- Footer (static) → hydrate? Why?
Without partial hydration: load entire React (~45 KB) + all component code
With partial hydration: load only Comments + ShareButtons code
Implementation in Astro (Islands Architecture)
Astro implements partial hydration via client:* directives:
---
// src/pages/article/[slug].astro
import ArticleHeader from '@/components/ArticleHeader.astro'; // Server
import ArticleContent from '@/components/ArticleContent.astro'; // Server
import CommentSection from '@/components/CommentSection.tsx'; // React, needs hydration
import ShareWidget from '@/components/ShareWidget.svelte'; // Svelte, needs hydration
import NewsletterForm from '@/components/NewsletterForm.vue'; // Vue, needs hydration
const { slug } = Astro.params;
const article = await getArticle(slug);
---
<html>
<body>
<!-- Zero JS — pure HTML -->
<ArticleHeader title={article.title} author={article.author} />
<ArticleContent content={article.content} />
<!-- Hydrate when visible in viewport -->
<CommentSection articleId={article.id} client:visible />
<!-- Hydrate on first interaction -->
<ShareWidget url={Astro.url.href} client:idle />
<!-- Immediate hydration (critical content) -->
<NewsletterForm client:load />
</body>
</html>
Hydration directives:
| Directive | When JS loads |
|---|---|
client:load |
Immediately on page load |
client:idle |
After requestIdleCallback (browser not busy) |
client:visible |
When component enters viewport |
client:media="..." |
When media query matches |
client:only="react" |
Client-only, no SSR |
Implementation in Next.js via dynamic import
import dynamic from 'next/dynamic';
// These components NOT included in initial bundle
const CommentSection = dynamic(() => import('@/components/CommentSection'), {
ssr: false,
loading: () => <CommentsSkeleton />,
});
const VideoPlayer = dynamic(() => import('@/components/VideoPlayer'), {
ssr: false, // No point rendering on server
});
const HeavyChart = dynamic(() => import('@/components/analytics/HeavyChart'), {
ssr: false,
loading: () => <div className="h-64 animate-pulse bg-gray-100 rounded" />,
});
// Hydrate when visible in viewport — native IntersectionObserver
function LazyHydrate({ children, rootMargin = '200px' }) {
const [hydrated, setHydrated] = useState(false);
const ref = useRef<HTMLDivElement>(null);
useEffect(() => {
const observer = new IntersectionObserver(
([entry]) => { if (entry.isIntersecting) setHydrated(true); },
{ rootMargin }
);
if (ref.current) observer.observe(ref.current);
return () => observer.disconnect();
}, []);
return <div ref={ref}>{hydrated ? children : <div style={{ minHeight: '1px' }} />}</div>;
}
// Usage
export default function ArticlePage({ article }) {
return (
<article>
<ArticleHeader article={article} /> {/* Server, 0 JS */}
<ArticleBody content={article.content} /> {/* Server, 0 JS */}
<LazyHydrate>
<CommentSection articleId={article.id} />
</LazyHydrate>
</article>
);
}
Progressive hydration
Hydrate components in sequence, not blocking main thread:
'use client';
import { useEffect, useState } from 'react';
// Hydration scheduler via requestIdleCallback
function useIdleHydration(delay = 0): boolean {
const [ready, setReady] = useState(false);
useEffect(() => {
let id: number;
if ('requestIdleCallback' in window) {
id = requestIdleCallback(() => setReady(true), { timeout: delay || 2000 });
} else {
id = setTimeout(() => setReady(true), delay) as unknown as number;
}
return () => {
'requestIdleCallback' in window
? cancelIdleCallback(id)
: clearTimeout(id);
};
}, [delay]);
return ready;
}
function IdleComponent({ children, fallback }: IdleProps) {
const ready = useIdleHydration(1000);
return ready ? children : fallback;
}
Measuring the effect
Tools to assess before and after partial hydration:
# Webpack Bundle Analyzer
npx @next/bundle-analyzer
# Astro Check: which components add JS
npx astro check
# Lighthouse CLI for automation
npx lighthouse https://example.com --output json \
--only-categories=performance \
| jq '.categories.performance.score'
Metrics that change:
| Metric | Expected improvement |
|---|---|
| Total Blocking Time (TBT) | -40–70% |
| Time to Interactive (TTI) | -30–60% |
| JS Parse/Execute time | -50–80% |
| Lighthouse Performance Score | +10–25 points |
When partial hydration is impractical
Partial Hydration doesn't make sense for:
- SPAs with rich interactivity on every page
- Apps where almost all components are client-side
- Dashboards behind authentication — SEO not important, JS loads once
Maximum benefit on public content pages: blogs, documentation, catalogs, landing pages.
Implementation timeline
- Week 1: audit JS bundle, identify components without client logic, profile TTI
-
Week 2–3: mark components as server/client, implement directives (
client:visible,client:idle) ordynamic()withssr:false - Week 4: LazyHydrate wrappers for scroll-below-the-fold content, measure metrics
- Week 5: regression testing, Lighthouse CI in pipeline, documentation