Граница 'use client' и почему она заразна

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

Требование «раньше всего остального» — не придирка к стилю. Строка считается директивой только в прологе файла: выше неё можно поставить комментарии и пустые строки, но ни одной инструкции. Один import сверху — и это уже не директива, а бесполезное выражение посреди кода.

// Директива живёт в «прологе» файла: до неё разрешены комментарии и пустые
// строки, но ни одной инструкции. Проверим это правило на двух файлах.
function isClientEntry(source: string): boolean {
  for (const raw of source.split("\n")) {
    const line = raw.trim();
    if (line === "" || line.startsWith("//")) continue;
    // первая же настоящая строка решает всё: либо директива, либо пролог кончился
    return line === "\"use client\";" || line === "\"use client\"";
  }
  return false;
}

const withComment = "// панель фильтров\n\"use client\";\nimport { useState } from \"react\";";
const afterImport = "import { useState } from \"react\";\n\"use client\";";

console.log(isClientEntry(withComment));
console.log(isClientEntry(afterImport));

Ошибка от этого получается обидная: сборка падает не на самой строке, а на первом хуке — Next сообщает, что useState работает только в клиентском компоненте, и советует пометить файл директивой. Директива стоит, вы её видите и не понимаете, чего от вас хотят. Смотреть нужно не на наличие строки, а на то, что стоит выше неё.

Директива помечает файл целиком, а не отдельный компонент. Если из пяти компонентов в файле браузер нужен одному — это повод разнести их по файлам, а не помечать все пять.

Серверный компонент выполняется один раз и превращается в описание разметки. Продолжения во времени у него нет: некому запомнить, что кнопку нажали, и некому эту кнопку слушать. В части II вы собирали такой цикл руками — состояние, перерисовка, делегирование событий, — и весь тот код по необходимости жил в браузере. Ничего не изменилось: он и сейчас должен быть там.

"use client";

// Кнопка помнит число нажатий между кликами — такой код на сервере бессмыслен:
// сервер отдал разметку и забыл о ней, продолжения во времени у него нет
function Counter() {
  const [count, setCount] = React.useState(0);
  console.log("рендер Counter, count =", count);
  return (
    <button id="inc" onClick={() => setCount(count + 1)}>
      Нажато: {count}
    </button>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Counter />);

// нажимаем за читателя, но не сразу: первая отрисовка случается не в этой строке
setTimeout(() => document.getElementById("inc")!.click(), 100);

Директива в примере стоит для правдоподобия: песочница про неё ничего не знает, для неё это просто строка. Разбирает директивы сборщик Next, а не браузер и не компилятор TypeScript.

Список того, что тянет за собой границу, короткий и запоминается целиком.

Обратная половина таблицы важнее первой. Компонент, который берёт пропсы и возвращает разметку, прекрасно работает на сервере — даже если внутри у него условия, циклы и форматирование. Такие компоненты в приложении составляют большинство, и держать их серверными ничего не стоит.

await границы не требует: серверный компонент умеет дожидаться данных сам, без useEffect. Об этом — отдельная статья главы.

Директива стоит в одном файле, но помечает не его одного. С этого файла сборщик идёт по импортам вглубь, и всё, до чего дойдёт, компилирует для браузера. Посчитаем клиентскую часть сами — обходом графа, тем же способом, каким это делает сборщик.

// Дерево импортов приложения: кто кого импортирует
const imports: Record<string, string[]> = {
  "app/post/page.tsx": ["app/post/article.tsx", "app/post/like-button.tsx"],
  "app/post/article.tsx": ["lib/format.ts"],
  "app/post/like-button.tsx": ["lib/format.ts", "lib/track.ts"],
  "lib/format.ts": [],
  "lib/track.ts": ["lib/queue.ts"],
  "lib/queue.ts": []
};

// Директива стоит ровно в одном файле — с него начинается клиентская часть
const entries = ["app/post/like-button.tsx"];

function clientBundle(graph: Record<string, string[]>, entries: string[]): string[] {
  const seen = new Set<string>();
  const queue = [...entries];
  while (queue.length > 0) {
    const file = queue.shift()!;
    if (seen.has(file)) continue;
    seen.add(file);
    // граница объявлена один раз, но расходится по всем импортам вглубь
    queue.push(...(graph[file] ?? []));
  }
  return [...seen].sort();
}

console.log(clientBundle(imports, entries));

Директива одна, файлов в браузере четыре. И два из них попали туда не потому, что кто-то так решил, а по цепочке: lib/track.ts импортирован кнопкой, а lib/queue.ts — самим track, о котором при расстановке директивы никто и не думал.

Отсюда два следствия. Первое: файлам ниже границы своя директива не нужна — они уже клиентские. Написать её там не ошибка, но это шум: читатель кода начнёт искать, зачем понадобился ещё один вход. Второе: lib/format.ts живёт в обоих мирах и компилируется дважды — это нормально ровно до тех пор, пока в нём нет ничего серверного. Кто в Next на самом деле режет граф и как один файл попадает сразу в несколько слоёв сборки, видно по файлам настоящей сборки.

Заразность идёт вниз по импортам, а не вверх по разметке. Родитель клиентского компонента остаётся серверным. И то, что клиентский компонент получил пропсом, тоже может остаться серверным — об этом следующая статья.

Раз директива заразна, место для неё выбирают не там, где удобно писать, а там, где дешевле платить. Проверить это можно, не выходя из браузера: React ведёт себя точно так же, только вместо «уехало в бандл» у него «перерисовалось». Одна и та же страница, две границы — сравните вывод.

function Article({ tag }: { tag: string }) {
  console.log("рендер Article", tag);
  return <p>Текст статьи, который от нажатий не меняется</p>;
}

// A: состояние подняли в страницу
function PageA() {
  const [likes, setLikes] = React.useState(0);
  return (
    <section>
      <Article tag="A" />
      <button id="a" onClick={() => setLikes(likes + 1)}>A: {likes}</button>
    </section>
  );
}

// B: состояние осталось в кнопке
function LikeButton() {
  const [likes, setLikes] = React.useState(0);
  return <button id="b" onClick={() => setLikes(likes + 1)}>B: {likes}</button>;
}

function PageB() {
  return (
    <section>
      <Article tag="B" />
      <LikeButton />
    </section>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <div>
    <PageA />
    <PageB />
  </div>
);

// нажимаем обе кнопки за читателя
setTimeout(() => document.getElementById("a")!.click(), 100);
setTimeout(() => document.getElementById("b")!.click(), 200);

После клика по левой кнопке Article рисуется заново, после клика по правой — нет. В браузере цена этому — лишний вызов функции; на сервере она другая и куда крупнее: в варианте A статья вместе со всеми своими импортами уехала бы в браузер, а в варианте B она остаётся разметкой, которую браузер получает готовой. Правило одно на оба случая: держите состояние — и границу — как можно ниже.

На практике это значит: из большого компонента вырезается маленький интерактивный кусок, и директива достаётся только ему.

// ── app/post/like-button.tsx ── здесь и проходит граница
"use client";

interface LikeButtonProps {
  initial: number;
}

function LikeButton({ initial }: LikeButtonProps) {
  const [likes, setLikes] = React.useState(initial);
  return <button onClick={() => setLikes(likes + 1)}>Нравится: {likes}</button>;
}

// ── app/post/page.tsx ── директивы нет: страница осталась серверной
function PostPage() {
  return (
    <article>
      <h1>Граница проходит ниже</h1>
      <p>Текст приезжает разметкой, кода браузеру на него не нужно.</p>
      <LikeButton initial={12} />
    </article>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<PostPage />);

В песочнице оба компонента лежат в одном файле, потому что она выполняет ровно один, и монтирование написано руками. В проекте это два файла, страница уходит через export default, а директива стоит только в файле кнопки.

Граница проходит по сборке, а типы через неё видны как обычно: пропсы клиентского компонента проверяются там же, где и всегда. Компилятор про границу ничего не знает — и это к лучшему, потому что ошибку он ловит одинаково по обе стороны.

"use client";

interface LikeButtonProps {
  initial: number;
}

function LikeButton({ initial }: LikeButtonProps) {
  const [likes, setLikes] = React.useState(initial);
  return (
    <button id="like" onClick={() => setLikes(likes + 1)}>
      Нравится: {likes}
    </button>
  );
}

// серверная часть отдала число строкой
ReactDOM.createRoot(document.getElementById("root")!).render(<LikeButton initial="0" />);
setTimeout(() => document.getElementById("like")!.click(), 100);
setTimeout(() => console.log("на кнопке:", document.getElementById("like")!.textContent), 200);

Диагностика есть, а кнопка всё равно нарисовалась и посчитала: строка "0" доехала до useState, и первое же нажатие превратило её в "01" — сложение строки с числом из части I. Типы живут до сборки, в браузер уезжает обычный JavaScript, поэтому диагностику компилятора нельзя пролистывать: за границей она единственная, кто предупредит.

Обратный ход — поставить директиву в раскладку — цепляет всё, что раскладка импортирует: шапку, меню, логотип и их зависимости. Сама страница клиентской при этом не станет, она приезжает в раскладку через children уже готовой, но шапка уедет в браузер целиком — из-за одной кнопки внутри неё. Дешевле вынести кнопку в свой файл: директива достанется ей одной.

Слово «клиентский» подсказывает больше, чем есть на самом деле, и из этого растут четыре устойчивых заблуждения.

Первая строка таблицы — самая дорогая на практике. Тело клиентского компонента выполняется дважды, и первый раз это происходит там, где нет ни window, ни localStorage. Поэтому обращения к браузеру живут в эффекте или в обработчике, а не в теле компонента.

"use client";

function Theme() {
  console.log("рендер: это выполнится и на сервере, и в браузере");
  React.useEffect(() => {
    console.log("эффект: только в браузере — здесь window уже существует");
  }, []);
  return <p>Тема оформления</p>;
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Theme />);

Песочница — это браузер, здесь window есть всегда, и падения на первом рендере вам не показать. Порядок строк в выводе, впрочем, настоящий: тело компонента раньше эффекта.

Разница между «серверным компонентом» и «серверным рендером клиентского» стоит того, чтобы её развести окончательно, — этому посвящена статья «Серверный компонент, SSR и гидратация — три разные вещи». Пока достаточно правила: директива не отменяет серверный рендер, она добавляет к нему браузерную жизнь.