'use client' and serializable props

'use client' marks the module — and everything it imports — as the client boundary, not a single component. The directive sits at the top of a file. From that file down through its import graph, code runs (and ships) on the client. A Server Component that renders a 'use client' component is the boundary’s parent; the directive’s job is to tell the bundler “from here on, this subtree is client”. So the unit you’re marking is never “this one component” — it’s “this module and everything reachable from it”.

// likes-button.tsx
'use client';
import { useState } from 'react';
import { formatCount } from './format';   // <- this module is now CLIENT too

export function LikesButton({ initial }: { initial: number }) {
  const [n, setN] = useState(initial);
  return <button onClick={() => setN(n + 1)}>{formatCount(n)} likes</button>;
}

formatCount had no directive of its own, but importing it from a client module pulls it across. The practical senior consequence: a 'use client' file at the top of a deep import tree drags that whole tree into the client bundle. Put the directive on the leaf that actually needs interactivity, not on a layout that imports half your app.

Props passed from a Server Component to a Client Component must be serializable. The boundary is a real wire: the server renders, and the props for each client island are serialized into the payload the browser hydrates from. Serializable means the things RSC can encode — primitives, plain objects and arrays of serializable values, Date, Map, Set, server-action references, JSX (ReactNode), and Promises of serializable values. Not serializable: arbitrary functions, class instances, and any object you’re passing for its behavior rather than its data.

// page.tsx  (Server Component — no directive)
import { LikesButton } from './likes-button';

export default async function Page() {
  const post = await db.post.find();        // class instance? -> map to plain data
  return (
    <LikesButton
      initial={post.likes}                   // number — fine
      // onLiked={() => track('like')}       // function — CANNOT cross; throws
    />
  );
}

Why “no functions”? A function is opaque behavior — the server can’t ship the closure to the browser and have it mean the same thing. The blessed exception is a server action ('use server'), which is passed as a reference the client can invoke, not as a live closure. So callbacks cross the boundary as server actions, not as plain functions.

You compose Server content into a Client Component through children (or any ReactNode slot) — you do not import a Server Component into a 'use client' file. This is the move that confuses people. A Client Component can’t import a Server Component (the import graph rule from Step 1 would turn the Server Component into client code, losing its server-only powers like direct DB access). But it can render server-rendered content that’s handed to it as a prop. The Server Component stays on the server; its already-rendered output is passed down as children and the client shell just slots it in.

// client shell — owns interactivity (open/close), knows nothing about its content
'use client';
import { useState } from 'react';

export function Collapsible({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <section>
      <button onClick={() => setOpen(o => !o)}>{open ? 'Hide' : 'Show'}</button>
      {open && children}
    </section>
  );
}

// server page — composes a SERVER component into the client shell as children
import { Collapsible } from './collapsible';
import { ServerReport } from './server-report';   // a Server Component (DB access etc.)

export default function Page() {
  return (
    <Collapsible>
      <ServerReport />     {/* rendered on the server; passed in as children */}
    </Collapsible>
  );
}

Collapsible never imports ServerReport. The parent (a Server Component) imports both and wires them together. That’s the “compose, don’t import across” rule: server content flows into client components as children, never across via an import.

The two failure modes, named so you spot them on sight. Failure A: passing a non-serializable prop across the boundary — a function, a class instance, a live object meant for behavior. You’ll see Functions are not valid as a child of Client Components or Only plain objects ... can be passed. The fix is to pass data (serialize the instance to a plain object) and pass callbacks as server actions. Failure B: importing a Server Component into a 'use client' module — by the Step 1 rule that re-tags the Server Component as client, so its server-only code (DB clients, secrets, fs) either breaks the build or, worse, leaks toward the browser. The fix is to invert: don’t import it; receive it as children from a server parent.

// ❌ Failure B: a Server Component imported into a client file
'use client';
import { ServerReport } from './server-report';   // now client; DB access breaks
export function Panel() { return <div><ServerReport /></div>; }

// ✅ Fix: take it as children, let a server parent supply it
'use client';
export function Panel({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>;
}

When not to push a boundary at all: if a subtree has no interactivity, leave it as Server Components — no directive, no serialization tax, no client bytes. 'use client' is a cost (serialization + bundle), so place it at the smallest leaf that genuinely needs browser-only APIs or state.