server-only and secrets: the module graph, NEXT_PUBLIC_, and what taint APIs actually catch

The module graph decides what ships to the browser

If you have ever wondered how a secret could end up in a public JS bundle when you never intentionally put it there, the answer is the transitive import rule — and understanding it changes how you structure any module that touches credentials.

In the App Router, “server code” and “client code” are not separate folders — they are regions of one module graph, split by the 'use client' directive. A file with 'use client' and everything it imports, transitively, must be bundleable for the browser. That transitive clause is where leaks live: you import one innocent helper from lib/billing.ts into a client component, and the bundler pulls the entire module — including the parts that touch secrets — into the client graph. The module’s top-level code now executes in the browser; any string literal in it ships verbatim in a public chunk.

Environment variables follow two different rules, and conflating them is the classic mistake. Plain server env vars (process.env.STRIPE_SECRET_KEY) are read at runtime on the server; if that code ends up in a client bundle, the value is undefined in the browser — a crash or a silent failure, embarrassing but not a leak. NEXT_PUBLIC_-prefixed vars are the opposite: they are inlined at build time — the bundler string-replaces process.env.NEXT_PUBLIC_X with the literal value everywhere it appears. Three consequences: the value is visible to anyone who opens devtools; it cannot be rotated without a rebuild and redeploy (the old value lives on in cached chunks until they expire); and the prefix is a one-way door — once a secret has shipped under NEXT_PUBLIC_, it is compromised, full stop, and rotation is the only remedy. The prefix is for genuinely public config: analytics ids, public API URLs. Anything you would not paste into a tweet does not get the prefix.

server-only: a build-time tripwire

The defense is not vigilance — it is making the wrong import fail the build. The server-only package contains no runtime code; its trick is in package.json export conditions: when resolved in a server context it resolves to an empty module, and when a client bundle tries to include it, it resolves to a module that throws a build error. One import line at the top of any module that must never reach the browser turns “a developer imported the wrong file” from a silent leak into a red build:

// lib/billing.ts
import 'server-only';                // client import of this module = build error
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function chargeCustomer(customerId: string, amountCents: number) {
  return stripe.charges.create({ customer: customerId, amount: amountCents, currency: 'usd' });
}

// The innocent-looking helper that tempts client imports — now safely fenced:
export function formatAmount(cents: number) {
  return (cents / 100).toFixed(2);
}

The discipline that makes this cheap: put import 'server-only' in every module that reads secrets, touches the database, or wraps a privileged SDK — reflexively, the way you write types. Pure formatting helpers that clients legitimately need go in their own lib/format.ts with no secret-bearing siblings, so nobody is ever tempted to import across the fence. The mirror package client-only exists for the reverse mistake (browser-API code pulled into server rendering). The cost of the tripwire is one import line; the failure it converts is the three-week incident from the Hook into a thirty-second build error pointing at the offending import chain.

Data leaks: serialized props, DTOs, and what taint actually does

Code is one leak channel; data is the other. Every prop you pass from a server component to a client component is serialized into the RSC payload — embedded in the HTML document and in subsequent navigation responses, fully visible in view-source. The classic incident shape: getUser() returns the whole database row, a server component passes user to a client <ProfileCard>, and passwordHash, mfaSecret, and stripeCustomerId are now in the page source for anyone — no breach, no exploit, just serialization doing its job on data that should never have crossed. The structural fix is the DTO discipline from the auth docs: data-access functions return explicitly constructed objects with the fields the UI needs, never the raw row. The leak then requires someone to add a sensitive field to a DTO on purpose, instead of requiring everyone to remember to strip it everywhere.

React’s taint APIs are a second tripwire for this channel, and they deserve an honest description. experimental_taintObjectReference(message, user) makes React throw at render time if that exact object reference is passed to a client component; experimental_taintUniqueValue(message, lifetime, secret) does the same for a specific primitive value. The limits matter as much as the feature: both are experimental (behind the taint flag); object tainting tracks the reference, so { ...user } produces an untainted copy that sails through; value tainting tracks the exact value, so any derivation — uppercase, base64, substring — escapes it. And both fire at runtime, not build time: a taint violation on a rarely rendered admin page is found when that page renders, not when it merges. Taint is defense-in-depth that catches the honest mistake of passing a flagged object directly; it is not a security boundary, and it does not replace DTOs — it backs them up.