Skip to main content

Fixing 'Text Content Did Not Match' and Caching Gotchas in Next.js 15

 Few things break a developer's flow like the console turning red with Warning: Text content did not match. Server: "10/24/2024" Client: "10/25/2024".

With the release of Next.js 15, we are seeing a resurgence of hydration errors due to stricter React 19 behaviors, coupled with confusion regarding the complete overhaul of fetch caching defaults.

This post dissects the mechanics of hydration mismatches caused by non-deterministic rendering and corrects the implementation patterns for data fetching in the Next.js 15 App Router.

Part 1: The Hydration Mismatch

The Root Cause: Non-Deterministic Rendering

React's hydration process expects the initial DOM generated by the browser to be byte-for-byte identical to the HTML returned by the server. When a component renders something non-deterministic—like new Date(), Math.random(), or window.localStorage—during the initial render pass, the server snapshot differs from the client's first paint.

React 19 (which powers Next.js 15) is unforgiving here. It won't just patch the difference silently; it flags it as a potential logic error because the initial UI state was unstable.

Solution 1: The suppressHydrationWarning Hatchet

For simple text mismatches, such as timestamps in a footer, React provides an escape hatch. This prop instructs React's reconciliation algorithm to ignore attribute or text content differences for that specific element only (it is not recursive).

export default function Timestamp() {
  // This will inevitably differ between Server time and Client time
  const time = new Date().toLocaleTimeString();

  return (
    <span suppressHydrationWarning>
      Generated at: {time}
    </span>
  );
}

Solution 2: The useHydrated Hook (The Surgical Fix)

For complex UI elements dependent on browser APIs (like LocalStorage or specific window dimensions), suppressHydrationWarning is insufficient. You need to ensure the render output is identical on the server and the first client pass, only updating once hydration is complete.

We solve this with a custom useHydrated hook.

// hooks/use-hydrated.ts
import { useState, useEffect } from 'react';

export function useHydrated() {
  const [isHydrated, setIsHydrated] = useState(false);

  useEffect(() => {
    setIsHydrated(true);
  }, []);

  return isHydrated;
}

Implementation:

// components/browser-feature.tsx
'use client';

import { useHydrated } from '@/hooks/use-hydrated';

export default function BrowserFeature() {
  const isHydrated = useHydrated();
  
  // 1. Server & First Client Render: Returns null (Deterministic)
  if (!isHydrated) {
    return <div className="h-10 w-full animate-pulse bg-gray-200 rounded" />; // Skeleton loader
  }

  // 2. Hydrated Render: Safe to access window/random/dates
  const randomValue = Math.floor(Math.random() * 100);

  return (
    <div className="p-4 border rounded shadow-sm">
      <p>Your lucky number: {randomValue}</p>
    </div>
  );
}

Why this works: The useEffect inside useHydrated only runs after the initial paint. By returning a skeleton or null initially, we guarantee the Server HTML and the Client's first VDOM pass match perfectly.

Part 2: Next.js 15 Fetch Caching Gotchas

The Root Cause: The Shift from "Cache by Default"

In Next.js 14, fetch requests were cached by default (force-cache). This confused developers who expected standard web API behavior (where requests are dynamic).

Next.js 15 changes the default: fetch requests inside Server Components are now uncached by default (no-store) if they are not inside a specific scope that opts into caching.

If you are upgrading and your page performance drops or you are hitting API rate limits, it is likely because your "static" pages are now dynamically fetching data on every request.

The Fix: Explicit Cache Configuration

Do not rely on defaults. Implicit behavior is the enemy of maintainable infrastructure. You must explicitly define your caching strategy.

Scenario A: Static Data (SSG Equivalent)

If the data rarely changes (e.g., a blog post, product footer), force the cache.

// app/blog/[slug]/page.tsx

interface Post {
  title: string;
  content: string;
}

async function getPost(slug: string): Promise<Post> {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    // EXPLICITLY opt-in to caching for Next.js 15
    cache: 'force-cache', 
  });

  if (!res.ok) throw new Error('Failed to fetch post');
  return res.json();
}

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const { slug } = await params; // Next.js 15 params are async
  const post = await getPost(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  );
}

Scenario B: Time-Based Revalidation (ISR Equivalent)

For data that needs to be fresh but not real-time (e.g., dashboard summaries), use next.revalidate.

// app/dashboard/stats/page.tsx

async function getStats() {
  const res = await fetch('https://api.example.com/stats', {
    next: { 
      // Re-fetch this data at most every 60 seconds
      revalidate: 60 
    },
  });
  
  return res.json();
}

Scenario C: Database Queries (Non-Fetch)

The fetch options above don't work for direct database calls (Prisma, Drizzle). In Next.js 15, use unstable_cache (which effectively wraps your function in a caching layer) to achieve standard React memoization across requests.

// lib/db-queries.ts
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';

export const getCachedUser = unstable_cache(
  async (userId: string) => {
    return await db.user.findUnique({ where: { id: userId } });
  },
  ['user-data'], // Cache Key
  {
    revalidate: 3600, // 1 hour
    tags: ['users']   // For on-demand revalidation
  }
);

Explanation: The params Await Trap

Notice in the code block for Scenario A:

const { slug } = await params;

In Next.js 15, params and searchParams in Page props are now Promises. Accessing them synchronously (params.slug) will throw a warning now and break in future versions. This is a common source of "undefined" errors during migration.

Conclusion

Next.js 15 pushes us towards standard web compliance and stricter React adherence. The "Text content did not match" error is a guardrail, not a bug, ensuring your UI state is predictable. Similarly, the removal of aggressive caching defaults forces us to be intentional about data freshness.

  1. Use suppressHydrationWarning for simple timestamps.
  2. Use a useHydrated hook for layout-shifting client logic.
  3. Explicitly set cache: 'force-cache' or revalidate options on your fetch calls; never assume the default.
  4. await your params.
Labels: