server-only и данные, текущие вниз

import "server-only" превращает утечку в ошибку сборки — применяй его к каждому модулю, который касается секрета или источника данных. Пакет server-only не экспортирует ничего полезного; его задача — уронить бандлер, если модуль оказался в клиентском графе. Ставь его в начало всего, что читает env-секреты, открывает соединение с БД или держит приватный ключ.

// lib/db.ts
import "server-only"; // ← если клиентский компонент импортирует это, сборка падает

import { Pool } from "pg";

// Никогда не достижимо из браузерного бандла: импорт выше это гарантирует.
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;
}

Без стража этот модуль работает — до того дня, когда кто-нибудь импортирует getUser (или хелпер, транзитивно его подтягивающий) из файла с "use client". Тогда драйвер pg, строка подключения и запрос — всё попадает в бандл и отдаётся. server-only делает такую ошибку неотгружаемой.

Загружай данные на сервере; серверный компонент — это граница данных. Серверный компонент — async, исполняется только на сервере и никогда не перерисовывается на клиенте, поэтому именно ему и принадлежит доступ к данным. Он напрямую вызывает server-only-модуль и порождает разметку страницы.

// app/users/[id]/page.tsx  — серверный компонент (без "use client")
import { getUser } from "~/lib/db";
import { PlanBadge } from "./PlanBadge"; // клиентский лист, ниже

export default async function UserPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const user = await getUser(id); // исполняется на сервере, с секретом
  if (!user) return <p>Not found.</p>;

  // Границу пересекают только нужные UI поля — не вся строка,
  // не соединение, не токен.
  return (
    <main>
      <h1>{user.name}</h1>
      <PlanBadge name={user.name} plan={user.plan} />
    </main>
  );
}

Серверный компонент держит опасные возможности (пул, env-переменную) и отдаёт клиенту только то, что тому нужно отрисовать. Ничего из внутренностей getUser не наблюдаемо из браузера.

Передавай вниз простые, сериализуемые данные — пропсы — это API границы. Всё, что ты отдаёшь клиентскому ребёнку, сериализуется и отправляется по проводу. Поэтому передавай примитивы, простые объекты и массивы — не экземпляры классов, не клиент БД, не функцию, замыкающую секрет. Клиентский компонент — это лист, который получает готовые данные и добавляет интерактивность.

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

import { useState } from "react";

// Получает только то, что рисует — уже загруженное, уже урезанное.
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>
  );
}

Ментальная модель: секреты и доступ остаются наверху, у серверного корня; простые данные текут вниз к интерактивным листьям. Клиентскому компоненту позволено быть интерактивным именно потому, что у него никогда не было возможности, которую стоит защищать, — он всегда видел только урезанный результат.

Режим отказа: секрет NEXT_PUBLIC_ или прямой импорт db в клиентском компоненте — настоящая утечка учётных данных. Две конкретные ошибки утекают продакшен-секреты к каждому посетителю, и обе легко допустить:

// ОТКАЗ 1 — префикс, отправляющий секрет в браузер.
// Всё NEXT_PUBLIC_* ВСТРАИВАЕТСЯ в клиентский JS на этапе сборки.
"use client";
const stripe = new Stripe(process.env.NEXT_PUBLIC_STRIPE_SECRET_KEY!); // 🔴 теперь публичный
// «Заработало», потому что значение было достижимо — вот и баг. Просмотр
// исходника его раскрывает. Лекарство — НИКОГДА не давай секрету префикс NEXT_PUBLIC_.

// ОТКАЗ 2 — затаскивание серверного модуля в клиентский граф.
"use client";
import { getUser } from "~/lib/db"; // 🔴 тянет pg + DATABASE_URL в бандл
//   — если в lib/db.ts есть `import "server-only"`, эта строка роняет СБОРКУ, а не
//   молча отгружает драйвер и строку подключения. В этом страже весь смысл.

NEXT_PUBLIC_ — для значений, которые должны быть публичными (опубликованный базовый URL API, ключ аналитики, рассчитанный на клиент). Секретный ключ с этим префиксом не «настроен» — он опубликован. А server-only существует именно для того, чтобы ОТКАЗ 2 был красной строкой в CI, а не разбором инцидента. Когда не стоит загружать на сервере вовсе: данные, привязанные к взаимодействию и принадлежащие клиенту (поиск с debounce, который пользователь печатает), по-прежнему живут в клиенте — но он должен вызывать route handler / server action, никогда не БД напрямую.