Shadcn/ui для Next.js: кастомизация тем

Руководство по добавлению и кастомизации тем shadcn/ui в проекте Next.js: от инициализации до dark mode. Примерное время выполнения: 45–90 минут.

shadcn/ui — набор компонентных примитивов, ориентированных на Tailwind CSS и SSR, поддерживаемый сообществом с быстрыми обновлениями в 2025 году. Библиотека предоставляет готовые шаблоны компонентов (кнопки, диалоги, тултипы), которые легко кастомизируются через CSS-переменные и Tailwind config. Для проектов на Next.js 14 это удобный компромисс между скоростью разработки и контролем над стилями: компоненты минимальны по уровню абстракции, что снижает риск переписывания стилей при оптимизации производительности.

ui?

Название проекта «shadcn/ui» часто вызывает вопрос: это UI-фреймворк или набор примитивов? На практике это набор компонентных примитивов (primitive components) и boilerplate для дизайна, не навязывающий жестких тем. В 2025 году библиотека сохраняет фокус на доступности (a11y) и лёгкости интеграции с Tailwind 4, что делает её подходящей для кастомных тем в Next.js-проектах.

Шаг 1: инициализация

Команда: создайте новый проект Next.js 14 и установите базовые зависимости (Node.js 20+, npm 10). Команды работают около 30–60 секунд на NVMe SSD и стабильном интернет-соединении.

npx create-next-app@14 my-shadcn-app --typescript
cd my-shadcn-app
npm install -D tailwindcss@4 postcss@8 autoprefixer
npx tailwindcss init -p

Пояснение: первая команда создаёт каркас Next.js 14 с TypeScript. Затем устанавливается Tailwind CSS 4 и генерируется файл tailwind.config.js и postcss.config.js.

Ожидаемый вывод (усечённый):

✔ Created project "my-shadcn-app"
added 234 packages, and audited 234 packages in 12s
initialized Tailwind CSS configuration
Wrote: tailwind.config.js
Wrote: postcss.config.js

Типичная ошибка: npx: command not found или несовместимая версия Node.

Как исправить: установите Node.js 20.x (2025) и убедитесь, что npx доступен. На Ubuntu/Debian используйте:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Шаг 2: установка компонентов

Команда: добавьте shadcn/ui, скрипт инициализации компонентов и необходимые peer-зависимости. Установки занимают около 10–25 секунд для npm на SSD.

npm install @shadcn/ui@0.11.0
npx shadcn-ui@0.11.0 init
npm install class-variance-authority@0.6 tailwind-merge@1.15

Пояснение: @shadcn/ui@0.11.0 — версия 2025 года, npx shadcn-ui init создаст директорию components и шаблоны для базовых компонентов. Дополнительные пакеты обеспечивают управление вариациями классов и объединение стилей.

Ожидаемый вывод:

+ @shadcn/ui@0.11.0
> shadcn-ui init
Scaffolding components in ./components/ui
Added Button, Input, Dialog, Dropdown
Success: Components added. Run npm run dev to start.

Типичная ошибка: shadcn-ui: command not found или Could not find peer dependency tailwindcss.

Как исправить: убедитесь, что Tailwind CSS установлен и корректно настроен в tailwind.config.js. Если npx не находит команду, используйте прямую ссылку на пакет: npx --package @shadcn/ui shadcn-ui init или установите пакет глобально для отладки.

Шаг 3: кастомная тема

Команда: добавьте файл с CSS-переменными темы и подключите их через :root и [data-theme="dark"]. Пример времени на правку — 5–10 минут.

/* styles/theme.css */
:root {
  --bg: 255 255 255;
  --fg: 17 24 39;
  --primary: 99 102 241; /* indigo-500 */
}
[data-theme="dark"] {
  --bg: 17 24 39;
  --fg: 241 245 249;
  --primary: 99 102 241;
}

/* глобальный импорт в _app.tsx */
import '../styles/theme.css'

Пояснение: shadcn/ui хорошо работает с токенами цвета в формате RGB, потому что Tailwind 4 поддерживает цвета через CSS-переменные и color: rgb(var(--fg) / ). Вы определяете переменные и переключаете наборы переменных через атрибут data-theme, это упрощает интеграцию с next-themes или собственным state.

Ожидаемый вывод: визуальная смена цветов при переключении атрибута data-theme в DOM. В dev-сервере изменения применяются мгновенно с HMR (Hot Module Replacement).

Пример изменения атрибута вручную в консоли браузера:

document.documentElement.setAttribute('data-theme', 'dark')

Типичная ошибка: Tailwind не собирает классы, использующие переменные, и вы видите некорректные цвета или отсутствует стиль.

Как исправить: убедитесь, что tailwind.config.js содержит правильные пути в content и добавляет расширение для CSS-переменных. Пример конфигурации:

module.exports = {
  content: ['./app/**/*.{ts,tsx,js,jsx}', './components/**/*.{ts,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: 'rgb(var(--primary) / )',
        bg: 'rgb(var(--bg) / )',
        fg: 'rgb(var(--fg) / )',
      }
    }
  },
  plugins: []
}

Шаг 4: подключение shadcn/ui компонентов

Команда: импортируйте готовые примеры компонентов и адаптируйте их к вашей theme. Время интеграции — 5–20 минут в зависимости от количества компонент.

import { Button } from '@/components/ui/button'

export default function Page() {
  return (
    Кнопка
  )
}

Пояснение: shadcn/ui компоненты обычно используют utility-классы Tailwind и допускают передачу className. В примере компонент Button получает классы из вашей темы (bg-primary связана с CSS-переменной).

Ожидаемый вывод: стилизованная кнопка, отрисованная с применением переменной --primary. В dev-сервере отобразится страница с кнопкой.

Типичная ошибка: компонент отображается без стилей или с дефолтными стилями.

Как исправить: проверьте, импортируется ли глобальный CSS (styles/globals.css, где подключён Tailwind и theme.css) в _app.tsx или app/layout.tsx. Также убедитесь, что класс name не перезаписывается.

Шаг 5: сборка и оптимизация

Команда: соберите проект и проверьте размер бандла. Пример времени сборки на CI с 2 vCPU и 8 ГБ ОЗУ — 60–180 секунд для средних приложений.

npm run build
npm run start

Ожидаемый вывод (фрагмент):

Next.js 14.0.0
> Build completed in 78s
> Size of client JS: 320 KB (gzip)
> Serverless pages: 5
Production server running on http://localhost:3000

Пояснение: сборка объединяет ваши компоненты shadcn/ui и стили Tailwind. Убедитесь, что не импортируете множество ненужных иконок или тяжелых библиотек, чтобы держать размер бандла низким.

Типичная ошибка: PostCSS plugin error или Failed to compile из-за несовместимых версий PostCSS/Tailwind.

Как исправить: проверьте версии PostCSS (8.x) и Tailwind (4.x). В CI используйте кэширование node_modules / pnpm store и включите анализ бандла (например, next build && next analyze). Для устранения лишних стилей используйте строгий список путей в tailwind.config.js и purge стратегию.

Как сделать dark mode?

Команда: установите next-themes@0.3.0 и создайте провайдер темы. Установка занимает ~5 секунд.

npm install next-themes@0.3.0

/* app/providers.tsx */
'use client'
import { ThemeProvider } from 'next-themes'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    {children}
  )
}

/* app/layout.tsx */
import '../styles/globals.css'
import { Providers } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    {children}
  )
}

Пояснение: next-themes управляет атрибутом data-theme на уровне html, что позволяет переключать наборы CSS-переменных. Атрибут attribute="data-theme" гарантирует совместимость с тем, как мы определили переменные в styles/theme.css.

Переключатель темы (компонент):

'use client'
import { useTheme } from 'next-themes'

export default function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  return (
    setTheme(theme === 'dark' ? 'light' : 'dark')}>
      Toggle theme
  )
}

Ожидаемый вывод: при клике на кнопку атрибут data-theme переключается, и тема меняется без полной перезагрузки страницы. Переключение происходит мгновенно, задержка обычно < 100 ms.

Типичная ошибка: flash of unstyled content (FOUC) — начальная отрисовка страницы видна в светлой теме, затем происходит переключение на тёмную.

Как исправить: используйте серверный рендеринг initial theme или добавьте скрипт в head, который применяет saved theme до загрузки React. Пример inline-скрипта (помещать с осторожностью, но он помогает):

(function() {
  try {
    const theme = localStorage.getItem('theme')
    if (theme) document.documentElement.setAttribute('data-theme', theme)
  } catch(e) {}
})()

Какие компоненты лучшие?

Рекомендации зависят от задач. Ниже — список наиболее полезных компонентов shadcn/ui для типичного приложения на Next.js 14 в 2025–2026 годах:

Почему эти компоненты: они минимальны, легко стилизуются через Tailwind/Tokens и не несут лишних runtime-зависимостей. В проектах с высокой нагрузкой предпочтительнее минимальные примитивы: они упрощают tree-shaking и снижают клиентский JS. Для примеров использования посмотрите статьи в разделе Frontend и UI на сайте.

Частые вопросы

Как shadcn/ui влияет на размер бандла?

shadcn/ui ориентирован на минимальные примитивы и Tailwind-утилиты, поэтому сам по себе добавляет небольшую долю к финальному бандлу — обычно сотни килобайт gzip для клиентской части. Критический фактор — сколько дополнительных библиотек и иконок вы импортируете. Для контроля размера применяйте динамический импорт (Next.js dynamic imports), анализируйте бандлы с помощью встроенных инструментов (next build && next analyze) и используйте строгую конфигурацию content в tailwind.config.js, чтобы убрать неиспользуемые стили.

Что делать, если Tailwind не применяет CSS-переменные?

Первый шаг — проверить пути в tailwind.config.js в секции content: они должны покрывать все компоненты и файлы, где используются utility-классы и переменные. Убедитесь, что глобальные CSS-файлы импортируются в app/layout.tsx или pages/_app.tsx. Если проблема сохраняется, проверьте порядок импортов (Tailwind base, components, utilities) и наличие PostCSS-плагинов. Наконец, перезапустите dev-сервер — иногда HMR не подхватывает новые конфигурации.

Почему возникает FOUC при переключении темы и как его предотвратить?

FOUC появляется, когда HTML отрисован на сервере без окончательного атрибута темы, а затем браузер применяет JavaScript для установки темы. Решения: (1) определить тему на сервере и отдать HTML с нужным data-theme; (2) добавить короткий inline-скрипт в head, который применяет сохранённую тему до загрузки React; (3) использовать стратегию скрытия тела до определения темы (менее предпочтительно). Наилучший вариант — SSR-определение темы или использование next-themes с серверной инициализацией.

Какая минимальная конфигурация для production на Vercel или Docker?

Для Vercel достаточно Next.js 14 + корректных build settings. Для Docker: базовый образ Node 20 (2025), выделите 2 vCPU и 4–8 ГБ ОЗУ для стабильной сборки и рантайма; образ с Node и Alpine имеет размер ~120–160 МБ. Для снижения размера используйте multi-stage build: собрать приложение в builder stage, а в финальный stage копировать только финальные артефакты. Убедитесь, что в контейнере настроены переменные окружения для NODE_ENV=production и корректно заданы порты (3000).

Когда стоит выбирать альтернативы shadcn/ui?

Если нужен монолитный дизайн-система с готовыми темами и компонентами с большим количеством готовых вариаций (например, Bootstrap или Material UI), shadcn/ui может оказаться слишком низкоуровневым. Выберите shadcn/ui, когда важно тонкое управление стилями и лёгкий runtime. Для быстрых admin-панелей с минимальной кастомизацией чаще подходят более комплексные UI-фреймворки.