Стили, сборка и выкладка

Доска из прошлых трёх статей размечена атрибутом style прямо в JSX — так было честно, пока проверялась раскладка. Для настоящих стилей это тупик: ни наведения, ни медиазапроса, ни тёмной темы в инлайновом объекте не выразить.

В части II классы column и card были зацепками для CSS, и уникальность имён держалась на внимании: .card в том проекте был ровно один. Здесь компонентов полтора десятка, и вторая .card появляется сама — вместе с чужой карточкой, которая внезапно перекрасилась.

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

// то, что даёт import styles from "./task-card.module.css":
// объект «локальное имя класса → итоговое имя в разметке»
const cardStyles = { card: "task-card_card__a1b2c", done: "task-card_done__f3e91" };
const boardStyles = { card: "board_card__7d40a", column: "board_column__11c8e" };

// в обоих файлах стилей написано «.card»
console.log(cardStyles.card);
console.log(cardStyles.card === boardStyles.card);

Никакой магии в разметке при этом нет: className получает обычную строку. Вся работа сборщика — переименовать классы так, чтобы совпасть они не могли, и склеить все модули в один файл стилей.

Место для файла определилось ещё в первой статье главы: модуль лежит папкой своего имени, а стили — рядом с разметкой, под тем же именем.

app/globals.css импортируется ровно один раз — в корневой раскладке app/layout.tsx. Его классы глобальны намеренно: body, :root, сброс полей. Всё остальное — по модулю на компонент.

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

За изоляцию имён приходится платить, и счёт выставляется в самом неудобном месте. Next объявляет любой модуль стилей как { readonly [key: string]: string } — ключи не перечислены. Прежде чем нажать Run, решите: что окажется в атрибуте class у заголовка?

// так Next объявляет любой *.module.css: ключи не перечислены
const styles: { readonly [key: string]: string } = {
  card: "task-card_card__a1b2c",
  title: "task-card_title__f3e91"
};

function TaskCard() {
  return (
    <article className={styles.card}>
      <h3 className={styles.titel}>Купить хлеб</h3>
    </article>
  );
}

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

// смотрим на разметку после коммита — как это сделал бы читатель в инспекторе
setTimeout(() => {
  const heading = document.querySelector("h3")!;
  console.log("class заголовка: " + JSON.stringify(heading.className));
  console.log("атрибут вообще есть: " + heading.hasAttribute("class"));
}, 50);

Ни диагностики компилятора, ни ошибки в браузере: атрибута просто нет. React не ставит class, если значение — undefined, поэтому опечатка в ключе выглядит как «стиль почему-то не применился». Искать такое приходится глазами.

// объект с индексной сигнатурой — ровно то, что приходит из import
const imported: { readonly [key: string]: string } = {
  card: "task-card_card__a1b2c",
  title: "task-card_title__f3e91"
};

// as, а не аннотация: с обязательными ключами тип из import не совместим —
// компилятор о его содержимом ничего не знает и назначить его отказывается
const styles = imported as Record<"card" | "title", string>;

console.log(styles.card);
console.log(styles.titel);

Карточка редко носит один класс: базовый, плюс модификатор состояния, плюс то, что передал родитель. Строка собирается в каждом компоненте, и это самое частое место, где классы тихо теряются. Предскажите обе строки вывода — обе печатаются через JSON.stringify, чтобы были видны пробелы.

const styles = { card: "task-card_card__a1b2c", done: "task-card_done__f3e91" };
const done = false;
const fromProps = undefined;

// привычный способ собрать className: массив с условиями и join
console.log(JSON.stringify([styles.card, done && styles.done].join(" ")));
console.log(JSON.stringify([styles.card, fromProps].join(" ")));

join зовёт String для каждого элемента, и false честно превращается в "false" — в атрибут class уезжает класс, которого нет ни в одном файле стилей. У null и undefined поведение другое, для них join подставляет пустую строку: получается хвостовой пробел и никакого сигнала, что данных не было.

Браузер на такое не жалуется: несуществующий класс — не ошибка. Значит, отсеивать пустые значения должны мы, и лучше в одном месте на весь проект. Функция на две строки закрывает вопрос — библиотека для этого не нужна.

type ClassValue = string | false | null | undefined;

// предикат вместо filter(Boolean): фильтр и так уберёт лишнее в рантайме,
// но только с предикатом тип результата станет string[], а не ClassValue[]
function cx(...values: ClassValue[]): string {
  return values.filter((value): value is string => Boolean(value)).join(" ");
}

const styles = { card: "card__a1b2c", done: "done__f3e91" };

console.log(cx(styles.card, false && styles.done));
console.log(cx(styles.card, true && styles.done, undefined));
console.log(JSON.stringify(cx(undefined, null, false)));

Тип ClassValue здесь важнее реализации: он разрешает передавать результат && — то есть false вместо строки — и запрещает всё остальное. Число или объект в cx компилятор уже не пропустит.

Теперь настоящая карточка доски. Она получает className от родителя, добавляет собственный модификатор и печатает итоговую строку на каждом рендере.

const styles = {
  card: "task-card_card__a1b2c",
  done: "task-card_done__f3e91"
};

type ClassValue = string | false | null | undefined;

function cx(...values: ClassValue[]): string {
  return values.filter((value): value is string => Boolean(value)).join(" ");
}

interface TaskCardProps {
  title: string;
  done: boolean;
  // класс от родителя: положение карточки — забота того, кто её ставит
  className?: string;
}

function TaskCard({ title, done, className }: TaskCardProps) {
  const cls = cx(styles.card, done && styles.done, className);
  console.log(JSON.stringify(cls));
  return <article className={cls}>{title}</article>;
}

function App() {
  const [done, setDone] = React.useState(false);
  return (
    <div>
      <TaskCard title="Купить хлеб" done={done} className="board_slot__7d40a" />
      <button id="toggle" onClick={() => setDone((value) => !value)}>готово</button>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
setTimeout(() => document.getElementById("toggle")!.click(), 50);

Класс от родителя стоит последним в строке — но на приоритет это не влияет: в CSS побеждает специфичность селектора, а при равной специфичности тот, кто ниже в собранном файле стилей. Порядок классов в атрибуте не значит ничего, и «перебить» чужой класс своим той же специфичности — лотерея. Надёжный способ — не перебивать, а дать компоненту пропс.

Последняя ловушка раздела ловится компилятором, и на неё стоит посмотреть живьём: в className попал весь объект стилей.

const styles = { card: "task-card_card__a1b2c" };

function TaskCard() {
  // объект целиком вместо строки — привычная опечатка на автодополнении
  return <article className={styles}>Купить хлеб</article>;
}

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

setTimeout(() => {
  console.log(document.querySelector("article")!.className);
}, 50);

Диагностика приходит до запуска, а браузер потом всё равно рисует карточку — с классом [object Object]. Это та же граница, что и во всей части: типы живут до сборки, а до страницы доезжает обычный JavaScript.

className={cx(...)} стоит писать даже там, где класс сейчас один. Второй появится через неделю, и место для него уже будет готово.

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

Общими их делают CSS-переменные. Сборщик переименовывает только классы; --accent остаётся --accent в любом модуле, потому что это часть каскада, а не имя из вашего файла.

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

interface ColumnProps {
  title: string;
  accent: string;
}

function Column({ title, accent }: ColumnProps) {
  // as здесь честнее любой обёртки: тип из @types/react перечисляет свойства CSS,
  // а пользовательских переменных в этом списке нет и быть не может
  const style = { "--accent": accent } as React.CSSProperties;
  return (
    <section style={style}>
      <h3 style={{ color: "var(--accent)" }}>{title}</h3>
    </section>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <Column title="В работе" accent="#c0392b" />
);

// проверяем не намерение, а результат: что реально посчитал браузер
setTimeout(() => {
  const heading = document.querySelector("h3")!;
  console.log(getComputedStyle(heading).color);
}, 50);

В выводе — rgb(192, 57, 43). Переменная задана на секции, а прочитал её вложенный заголовок: var() ищет значение вверх по дереву, и модули на этот поиск не влияют — они переименовывают классы, а не переменные. Проверяли мы при этом не намерение, а результат: getComputedStyle показывает то, что браузер посчитал на самом деле.

Приведение в этой строке — не небрежность. Тип React.CSSProperties перечисляет свойства CSS по именам, и пользовательских переменных в этом списке нет: в проекте литерал { "--accent": accent } без приведения компилятор отвергнет — «объектный литерал может использовать только известные свойства». Это тот редкий случай, когда as не прячет ошибку, а сообщает компилятору то, чего он знать не может: список ваших переменных не описан нигде.

Тёмная тема живёт в globals.css целиком: компоненты пишут var(--bg) и не знают, какая тема включена. Ни одного if по теме в разметке быть не должно.

// тема — это набор значений для одних и тех же имён
const THEMES: Record<"light" | "dark", React.CSSProperties> = {
  light: { "--bg": "#ffffff", "--text": "#1a1a1a" } as React.CSSProperties,
  dark: { "--bg": "#1a1a1a", "--text": "#f5f5f5" } as React.CSSProperties
};

function Board() {
  const [theme, setTheme] = React.useState<"light" | "dark">("light");
  // ни одного условия по теме ниже по дереву: карточка знает только имена
  return (
    <div style={{ ...THEMES[theme], background: "var(--bg)", color: "var(--text)", padding: 12 }}>
      <p>Купить хлеб</p>
      <button id="theme" onClick={() => setTheme((value) => (value === "light" ? "dark" : "light"))}>
        сменить тему
      </button>
    </div>
  );
}

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

const textColor = () => getComputedStyle(document.querySelector("p")!).color;
setTimeout(() => console.log("до: " + textColor()), 50);
setTimeout(() => document.getElementById("theme")!.click(), 100);
setTimeout(() => console.log("после: " + textColor()), 150);

next build — не «минификация на выходе». Это три разные работы подряд, и в логе они идут отдельными строками: Compiled successfully, Running TypeScript ..., Generating static pages ..., а в конце — таблица маршрутов с легендой значков. А самая первая строка, ещё до них, называет сборщик — словом в скобках после версии Next: без флагов это (Turbopack), а с флагом --webpack, который включает прежний сборщик, — (webpack).

Строка про TypeScript стоит того, чтобы её заметить. Сборка запускает ту же проверку типов, что и tsc из части III, и при несходящихся типах проект просто не собирается. Разработка себя так не ведёт: next dev страницу покажет — типы стираются, а код выполняется. «Работает локально» и «собирается» — разные утверждения, и второе строже.

Таблица маршрутов в конце — отчёт о том, что Next успел посчитать заранее. Для нашей доски она выглядит так (читать её подробно учит статья «Статика, динамика и всё между ними»).

Первая строка здесь — источник самого обидного бага выкладки. Доска собрана на сборке; посетитель, зашедший через час после добавления задачи, увидит её такой, какой она была в момент next build, — если действие не позвало revalidatePath. Под next dev это не воспроизводится никогда: там страница считается заново на каждый запрос.

Проверять проект надо командами next build и next start, а не разработкой. Заморозка страниц, вшитые переменные и забытый generateStaticParams видны только там.

Вторая вещь, которая случается именно на сборке, — подстановка переменных окружения. Всё, что начинается с NEXT_PUBLIC_, попадает в бандл значением. Предскажите, что станет с обеими строками исходника.

// упрощённая модель того, что делает сборка с исходником компонента
const source = "const api = process.env.NEXT_PUBLIC_API_URL;\n" +
  "const secret = process.env.DATABASE_URL;";

const env: Record<string, string> = {
  NEXT_PUBLIC_API_URL: "https://api.example.com",
  DATABASE_URL: "postgres://user:pass@db:5432/board"
};

function inline(code: string, values: Record<string, string>): string {
  return code.replace(/process\.env\.(\w+)/g, (whole: string, name: string) =>
    name.startsWith("NEXT_PUBLIC_") ? JSON.stringify(values[name]) : whole
  );
}

console.log(inline(source, env));

Публичная переменная превратилась в строковый литерал — её больше нет как переменной, поменять её в контейнере невозможно, только пересобрать образ. Серверная осталась обращением к process.env и будет прочитана в момент запроса, на сервере, куда браузер не заглядывает. Сама модель — регулярка: окажись process.env.NEXT_PUBLIC_API_URL внутри строкового литерала, она заменила бы и его. Настоящая подстановка идёт по дереву и строку с тем же текстом не тронет.

Отсюда странная на первый взгляд строка в Dockerfile учебника: адрес сайта приходит туда аргументом сборки, а не переменной окружения контейнера. Из NEXT_PUBLIC_SITE_URL строятся канонические ссылки и sitemap.xml, и подставляются они на сборке — переменной в рантайме их уже не исправить.

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

У сборки два разных конца. Обычная оставляет после себя приложение, которое нужно запустить: next start или server.js держат процесс Node, и каждый запрос проходит через ваш код. Строка output: "export" в next.config.ts заканчивает сборку папкой out/: готовые HTML, CSS и JavaScript, которые отдаст любой файловый сервер.

Выбирают между ними не по размеру сайта и не по вкусу. Правило одно: если в момент запроса должен выполниться ваш код — нужен процесс. Дальше остаётся сверить со списком.

Тот же список удобно держать функцией — и заодно проверить на двух настоящих проектах: нашей доске и этом учебнике.

type Feature =
  | "serverAction"
  | "cookies"
  | "revalidate"
  | "imageOptimize"
  | "generateStaticParams"
  | "clientState";

// всему в этом списке нужен код в момент запроса — файлу его взять неоткуда
const needsServer: readonly Feature[] = ["serverAction", "cookies", "revalidate", "imageOptimize"];

function decide(used: readonly Feature[]): string {
  const blockers = used.filter((feature) => needsServer.includes(feature));
  return blockers.length === 0
    ? "хватит папки out/"
    : "нужен процесс: " + blockers.join(", ");
}

// доска задач: форма добавления — действие, после мутации зовём revalidatePath
console.log(decide(["serverAction", "revalidate", "clientState"]));

// учебник, который вы читаете: страницы пререндерены, состояние живёт в браузере
console.log(decide(["generateStaticParams", "clientState"]));

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

Подробности жизни без процесса — generateStaticParams, правила отдачи файлов, заголовки кеша — разобраны в статье «Статический экспорт: сайт без Node на сервере». Здесь важно другое: этот выбор делается до того, как написана первая форма, а не в день выкладки. Переезд с действий на отдельный API — это переписанная половина проекта.

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

Доске нужен процесс — значит, в образ поедет Node. Класть туда весь проект с node_modules не нужно: output: "standalone" просит сборку собрать самодостаточный запуск. В .next/standalone появляется server.js и урезанный node_modules — только те файлы, до которых дотянулись импорты.

Запускается это командой node server.js. Порт берётся из переменной PORT — по умолчанию 3000, — а слушает сервер 0.0.0.0, то есть все интерфейсы контейнера: привяжись он к localhost, снаружи до него никто бы не достучался. Ни next, ни pnpm в рантайм-образе больше не нужны.

И сразу ловушка, ради которой стили и выкладка попали в одну статью: .next/static и public в standalone не копируются. Их кладут рядом руками. Симптом узнаваемый — страница открывается, разметка на месте, а стилей нет: в панели сети видно 404 на файл из /_next/static/css/.

Наружу этот контейнер сам не смотрит. Перед ним стоит обратный прокси — Caddy или nginx: он получает и продлевает сертификат, слушает 80 и 443, а внутрь ходит по имени сервиса — reverse_proxy web:3000. Приложение о HTTPS не знает ничего, и это правильно: сертификат — забота входа, а не вашего кода.

Сборка образа на маленьком VPS обрывается загадочно и без объяснений: next build не влезает в два гигабайта памяти. Лечится swap-файлом или сборкой образа не на сервере.

Теперь сверим с учебником, который вы читаете, — у него ровно тот же Next и совсем другая выкладка. В его next.config.ts стоит output: "export": сборка заканчивается папкой out/ со всеми статьями, и в рантайм-образе нет Node вообще — там caddy:2-alpine, которому просто отдали эту папку.

Разница в двух образах выросла из одной строки конфигурации, а та — из ответа на вопрос прошлого раздела. Ничего «продвинутого» в выкладке учебника нет: это буквально папка файлов и файловый сервер поверх неё.

Выложили — проверяйте на живом адресе, а не на localhost. Пять пунктов ловят почти все ошибки первого выката.

Последний пункт — не баг выкладки, а честная граница проекта: базы у нас нет, и задачи лежат в памяти сервера. Всё, что нужно, чтобы они пережили перезапуск, — тема части VI.