A senior engineer’s practical guide to ending the Next.js Server vs. Client Component confusion, focusing on real-world fixes for common “window is not defined” errors.

Did we finally agree on when to use Server vs Client Rendering in Next.js? My take.

It was 2 AM. PagerDuty was screaming its head off because our main customer dashboard was throwing 500 errors after a supposedly “minor” deployment. The on-call dev was stumped. I rolled out of bed, logged into our Kubernetes cluster in us-east-1, and started digging through logs. The error was maddeningly simple: ReferenceError: window is not defined. A junior dev had added a component that used a browser-only library for tracking analytics, and because Next.js now defaults to Server Components, it was trying to run browser code on a server. That night, I knew this wasn’t just a technical problem; it was a conceptual hurdle our entire team needed to get over, fast.

The Root of the Confusion: Your Code Has Two Homes Now

Let’s get this straight. The core issue isn’t that Next.js is “broken.” It’s that we, as developers, are mentally wired to think our React code always runs in the browser. With the App Router, that’s no longer true. By default, your component is a React Server Component (RSC). It runs on the server during the build or request time. It has direct access to the filesystem, databases (like our prod-db-01), and environment variables. What it doesn’t have is access to the browser’s window object, document, localStorage, or any browser-specific APIs.

When you need state (useState), effects (useEffect), or browser-only APIs, you need to explicitly tell Next.js, “Hey, this piece of the UI needs to run in the browser!” That’s where Client Components come in.

My Go-To Fixes, From Quickest to Cleanest

When a dev on my team comes to me with this problem, I don’t just give them the answer. I walk them through these three options, depending on the situation.

1. The “Just Make It Work” Fix: 'use client'

This is your escape hatch. It’s the fastest way to solve the problem. By placing 'use client' at the very top of a file, you’re telling Next.js, “This file and everything it imports is a Client Component. Don’t even try to render it on the server.”

Let’s say you have a component that needs to read a theme from localStorage.

'use client';

import { useState, useEffect } from 'react';

function ThemeToggleButton() {
  const [theme, setTheme] = useState('light');

  // This useEffect hook needs the 'window' object to access localStorage.
  // It would crash in a Server Component.
  useEffect(() => {
    const savedTheme = window.localStorage.getItem('theme') || 'light';
    setTheme(savedTheme);
  }, []);

  const toggleTheme = () => {
    const newTheme = theme === 'light' ? 'dark' : 'light';
    setTheme(newTheme);
    window.localStorage.setItem('theme', newTheme);
  };

  return <button onClick={toggleTheme}>Current Theme: {theme}</button>;
}

export default ThemeToggleButton;

Warning from the trenches: Don’t get trigger-happy and put 'use client' on every file. If you do that, you’re essentially opting out of Server Components entirely and losing all the performance benefits. You’ll have built a very complicated Create React App. Use this directive at the “leaves” of your component tree, not at the root.

2. The “Proper Architect” Fix: Smart Component Composition

The most elegant solution is often to separate your concerns. Keep server-side logic and data-fetching in Server Components, and pass that data as props to smaller, interactive Client Components.

Imagine a page that fetches user data from the server but has a client-side button to update their profile. You don’t need the whole page to be a Client Component.

Parent Server Component (e.g., /app/dashboard/page.tsx):

// This is a Server Component by default! No 'use client' needed.
import { db } from '@/lib/db';
import UserProfileClient from './UserProfileClient';

async function getUserData(userId) {
  // This code runs securely on the server.
  // It can access the database directly.
  const user = await db.user.findUnique({ where: { id: userId } });
  return user;
}

export default async function DashboardPage() {
  const user = await getUserData(123);

  // We fetch data on the server and pass it down.
  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      {/* The interactive part is isolated in a Client Component */}
      <UserProfileClient user={user} />
    </div>
  );
}

Child Client Component (e.g., /app/dashboard/UserProfileClient.tsx):

'use client';

import { useState } from 'react';

// This component only handles the interactive UI logic.
export default function UserProfileClient({ user }) {
  const [editing, setEditing] = useState(false);

  const handleEdit = () => {
    // This event handler requires this to be a Client Component.
    setEditing(!editing);
    // ... logic to show a form
  };

  return (
    <div>
      <p>Email: {user.email}</p>
      <button onClick={handleEdit}>
        {editing ? 'Cancel' : 'Edit Profile'}
      </button>
    </div>
  );
}

This is the pattern we strive for at TechResolve. It gives us the best of both worlds: fast initial page loads from the server and rich interactivity on the client.

3. The “Heavy Lifter” Fix: Dynamic Imports

Sometimes you have a big, complex library that is only needed on the client-side (think charting libraries, rich text editors, or map APIs). You don’t want to bundle that hefty JavaScript and send it to users who might not even see the component. For this, we use dynamic imports with SSR turned off.

'use client';

import { useState } from 'react';
import dynamic from 'next/dynamic';

// Dynamically import the heavy map component, and disable Server-Side Rendering for it.
const HeavyMapComponent = dynamic(() => import('@/components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>,
});

export default function LocationPicker() {
  const [showMap, setShowMap] = useState(false);

  return (
    <div>
      <button onClick={() => setShowMap(true)}>Show Location on Map</button>
      {/* The map component will only be loaded and rendered in the browser
          when the user actually clicks the button. */}
      {showMap && <HeavyMapComponent />}
    </div>
  );
}

This is a performance-tuning move. It keeps your initial bundle small and loads heavy components only when they are actually needed.

My Quick Reference Table

When in doubt, here’s the mental model I use:

So, have we agreed? I think so. The community is settling on these patterns. The default is server, for speed and security. You “opt-in” to client-side interactivity where you need it, and you do it as granularly as possible. It’s a shift in mindset, for sure, but once it clicks, you start building faster and more robust applications. And you get to sleep through the night without PagerDuty yelling at you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions