Composition Across the Boundary

## What people are actually worried about The fear is that a client provider at the top of the App Router tree "infects" everything under it — that once `app/layout.tsx` renders a component marked `'use client'`, every page, every card, every table below it is dragged into the browser bundle and loses server-side data access. That would make global providers unusable, since almost every real app needs one (theme, a query client, a toast portal). It does not happen, and the reason is worth being precise about. ## The boundary is a module-graph rule `'use client'` is a directive at the top of a **module**. It says: this module is an entry point into the client graph. Everything that module *imports* — transitively — is client code too. What it does **not** say is "every element that ends up rendered inside me is client code". Rendered-tree position and import position are different things. A prop is not an import. When the layout writes `<Providers>{children}</Providers>`, the layout is the one holding the reference to the page's element tree. `Providers` never imports the page and has no idea what it is; it receives an opaque node and renders it in place. ## The concrete shape in the App Router ```tsx // app/providers.tsx 'use client' import { ThemeContext } from './theme-context' export function Providers({ children }: { children: React.ReactNode }) { return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider> } ``` ```tsx // app/layout.tsx — no directive: still a Server Component import { Providers } from './providers' export const metadata = { title: 'App' } export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body><Providers>{children}</Providers></body> </html> ) } ``` What ships to the browser is `providers.tsx` plus whatever it imports. The page that lands in `{children}` is rendered on the server: it can be an `async` function, it can hit the database, it can read `cookies()` and `headers()` from `next/headers`, and none of that code is in the client bundle. Because the root layout keeps no directive, it also keeps the exports only server files may have — notably `metadata` and `generateMetadata`. Marking the layout itself `'use client'` would break those, which is one practical reason the provider is extracted into its own file instead of inlined. ## What the client provider receives During the server render, the page subtree is turned into the serialized RSC payload. The provider's `children` prop is a reference to that already-produced output. Two consequences follow: 1. **The provider cannot re-run the server subtree.** When the provider's own state changes, React re-renders the provider, but the `children` reference is unchanged, so React skips re-rendering that subtree entirely. Server components are not re-executed in the browser at all. Getting fresh server output requires a new server render — a navigation, or `router.refresh()` from `next/navigation`. 2. **The provider cannot inspect or alter the subtree meaningfully.** It can render it, wrap it in a `<div>`, or render it conditionally. It cannot reach in and re-parameterise it. ## The limitation that actually bites Context travels down the rendered tree, but only client components subscribe to it. A server component sitting inside `{children}` renders on the server, before any client provider exists, so it cannot read the theme, the auth object, or anything else in that context. Teams discover this when they try to move a server component's styling decision into a client theme context and find no way to read it. The fix is to source the value where the server can see it: a cookie read with `cookies()` in the layout or page, a request header, or config resolved server-side — and then hand it to the client provider as an initial value so both halves agree. ## Where to put it A provider only needs to sit above the components that consume it. Putting everything in the root layout is convenient but means that JavaScript loads on every route, including routes that never touch it. A provider used only by one section belongs in that section's layout, so the rest of the app never downloads it. ## The mistakes to avoid - Marking `app/layout.tsx` itself `'use client'` instead of extracting a provider file — that pulls the layout and its imports client-side and kills the `metadata` export. - Assuming a global client provider forces client rendering everywhere, and then giving up on server data fetching in pages. - Wrapping a third-party component that needs `'use client'` at the barrel/index level rather than in a thin dedicated wrapper file.