server-only and data flowing down

import "server-only" turns a leak into a build error — adopt it for every module that touches a secret or a data source. The server-only package exports nothing useful; its job is to fail the bundler if the module ends up in a client graph. Put it at the top of anything that reads env secrets, opens a DB connection, or holds a private key.

// lib/db.ts
import "server-only"; // ← if a client component imports this, the build fails

import { Pool } from "pg";

// Never reachable from the browser bundle: the import above guarantees it.
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function getUser(id: string) {
  const { rows } = await pool.query(
    "select id, name, plan from users where id = $1",
    [id],
  );
  return rows[0] ?? null;
}

Without the guard, this module works until the day someone imports getUser (or a helper that transitively pulls it in) from a "use client" file. Then the pg driver, the connection string, and the query all get bundled and served. server-only makes that mistake un-shippable.

Fetch on the server; the Server Component is the data boundary. A Server Component is async, runs only on the server, and never re-renders on the client — so it is exactly where data access belongs. It calls the server-only module directly and produces the markup for the page.

// app/users/[id]/page.tsx  — a Server Component (no "use client")
import { getUser } from "~/lib/db";
import { PlanBadge } from "./PlanBadge"; // a client leaf, below

export default async function UserPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const user = await getUser(id); // runs on the server, with the secret
  if (!user) return <p>Not found.</p>;

  // Only the fields the UI needs cross the boundary — not the whole row,
  // not the connection, not the token.
  return (
    <main>
      <h1>{user.name}</h1>
      <PlanBadge name={user.name} plan={user.plan} />
    </main>
  );
}

The Server Component holds the dangerous capabilities (the pool, the env var) and hands the client only what it must render. Nothing about getUser’s internals is observable from the browser.

Pass plain, serializable data down — props are the boundary’s API. Everything you give a client child is serialized and sent over the wire. So pass primitives, plain objects, and arrays — not class instances, not the DB client, not a function that closes over a secret. The client component is a leaf that receives finished data and adds interactivity.

// app/users/[id]/PlanBadge.tsx
"use client";

import { useState } from "react";

// Receives only what it renders — already fetched, already trimmed.
export function PlanBadge({ name, plan }: { name: string; plan: string }) {
  const [open, setOpen] = useState(false);
  return (
    <button onClick={() => setOpen((v) => !v)}>
      {plan}
      {open && <span> — {name} is on the {plan} plan</span>}
    </button>
  );
}

The mental model: secrets and access stay up at the server root; plain data flows down to interactive leaves. A client component is allowed to be interactive precisely because it never had a capability worth protecting — it only ever saw the trimmed result.

The failure mode: a NEXT_PUBLIC_ secret or a direct db import in a client component — a real credential exposure. Two specific mistakes leak production secrets to every visitor, and both are easy to make:

// FAILURE 1 — the prefix that ships the secret to the browser.
// Anything NEXT_PUBLIC_* is INLINED into client JS at build time.
"use client";
const stripe = new Stripe(process.env.NEXT_PUBLIC_STRIPE_SECRET_KEY!); // 🔴 now public
// "It worked" because the value was reachable — that's the bug. View source
// reveals it. The fix is NEVER prefix a secret with NEXT_PUBLIC_.

// FAILURE 2 — pulling a server module into a client graph.
"use client";
import { getUser } from "~/lib/db"; // 🔴 drags pg + DATABASE_URL into the bundle
//   — if lib/db.ts has `import "server-only"`, this line fails the BUILD instead
//   of silently shipping the driver and connection string. That guard is the point.

NEXT_PUBLIC_ is for values that are meant to be public (a published API base URL, an analytics key designed for client use). A secret key with that prefix is not “configured” — it is published. And server-only exists precisely so FAILURE 2 is a red CI line, not a postmortem. When not to fetch on the server at all: data that is per-interaction and client-owned (a debounced search the user types) still belongs in the client — but it should call a route handler / server action, never the DB directly.