Vivek's Blog

I've been building a React component library along with a playground site where people can preview each component before dropping it into their own project. Pretty standard setup: a docs page for every component, a live preview area, code snippets, the usual.

While building the documentation pages, I ran into this error in the console:

Text content does not match server-rendered HTML. Warning: Text content did not match. This tree will not be patched up. This can happen if a SSR-ed Client Component used...

Along with that, the site felt noticeably slow, especially when navigating from the homepage into an individual component's doc page. So I started digging into what was actually going wrong, and it raised a bigger question for me:

If a component playground keeps throwing hydration mismatches, should I just switch the whole thing to client-side rendering instead of fighting SSR?

What's actually causing the mismatch

Hydration errors happen when the HTML React renders on the server doesn't match what React produces on the client during the first render. A few usual suspects:

• Code that touches window, document, or localStorage during render instead of inside useEffect
• Values that change between server and client, like Date.now() or Math.random(), used directly in the render output
• Third-party UI or animation libraries that behave differently depending on whether they're running server-side or client-side
• Conditional rendering based on typeof window !== 'undefined', which by definition renders different output on each side

In my case, some of the components in the library just weren't written with SSR in mind, so pushing them through Next.js's SSR pipeline was the root of both the console errors and the sluggish page loads.

Weighing CSR against SSR for this specific use case

Once I found the actual cause, I had to think through whether switching the playground pages to full client-side rendering was the right call, or if it was overkill.

Where CSR helps:

• No more hydration mismatches, since there's nothing to compare against
• Way easier to use components that touch browser APIs without adding guards everywhere
• Matches the whole point of a playground page anyway: the user is there to interact with a live, running component

Where CSR hurts:

• Slower first paint. The user stares at a blank page or a spinner until the JS downloads and runs
• Worse SEO. If people are searching for something like "React date picker component" and landing on your docs page, you lose that if there's no server-rendered content for search engines to index
• A heavier JS bundle up front since nothing is pre-rendered
• No content at all for users on a slow connection or with JS disabled, though this is a smaller concern for most sites

The middle ground I landed on

Instead of flipping the entire site to CSR, I only disabled SSR for the actual live preview part of each page, and kept everything else (the title, description, props table, code examples) server-rendered as usual.

In Next.js this looks like:

import dynamic from 'next/dynamic';
 
const LivePreview = dynamic(() => import('./LivePreview'), { ssr: false });

This way the text-heavy parts of the docs stay indexable and fast to load, and the interactive preview, which is the part actually causing the mismatch, just renders client-side without any conflict.

It's the same rough pattern you'll find behind most component documentation sites out there. Feels like the right balance between SEO, load speed, and not fighting hydration errors all day.

Still early days on this project, but figured I'd write this down in case someone else runs into the same error while building something similar.