Руководство по добавлению и кастомизации тем shadcn/ui в проекте Next.js: от инициализации до dark mode. Примерное время выполнения: 45–90 минут.
К концу руководства вы получите рабочую интеграцию shadcn/ui в Next.js с настраиваемой темой и переключателем dark mode. Время выполнения полного сценария — примерно 45–90 минут на машине с SSD и 8 ГБ ОЗУ.
Что вы изучите
Инициализация проекта Next.js 14 (релиз 2025) и базовая настройка Tailwind CSS 4.
Установка и скелет shadcn/ui (версия 0.11.0, 2025) и интеграция компонентов.
Создание кастомной темы через CSS-переменные и Tailwind config.
Реализация переключателя dark mode с next-themes 0.3.0 и устранение FOUC.
Оптимизация сборки и рекомендации по производительности для Next.js 14.
Требования
Node.js 20.x (релиз 2025), npm 10.x или pnpm 8.x.
Next.js 14 (релиз 2025). Минимум 8 ГБ ОЗУ на локальной машине, 2 vCPU для тестовой сборки в CI.
Tailwind CSS 4 (релиз 2025), PostCSS 8.
Порты: dev сервер по умолчанию 3000. Для preview deploy используйте порт 3000 или 8080.
Около 120 МБ свободного места для node_modules после установки базовых пакетов; shadcn/ui добавляет ~200–400 КБ к сборке (gzip).
Почему shadcn
0
Статья была полезной?
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…
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 и стабильном интернет-соединении.
Пояснение: первая команда создаёт каркас 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 используйте:
Пояснение: @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 минут.
Пояснение: shadcn/ui хорошо работает с токенами цвета в формате RGB, потому что Tailwind 4 поддерживает цвета через CSS-переменные и color: rgb(var(--fg) / ). Вы определяете переменные и переключаете наборы переменных через атрибут data-theme, это упрощает интеграцию с next-themes или собственным state.
Ожидаемый вывод: визуальная смена цветов при переключении атрибута data-theme в DOM. В dev-сервере изменения применяются мгновенно с HMR (Hot Module Replacement).
Пример изменения атрибута вручную в консоли браузера:
Команда: импортируйте готовые примеры компонентов и адаптируйте их к вашей 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.
Ожидаемый вывод: при клике на кнопку атрибут data-theme переключается, и тема меняется без полной перезагрузки страницы. Переключение происходит мгновенно, задержка обычно < 100 ms.
Типичная ошибка: flash of unstyled content (FOUC) — начальная отрисовка страницы видна в светлой теме, затем происходит переключение на тёмную.
Как исправить: используйте серверный рендеринг initial theme или добавьте скрипт в head, который применяет saved theme до загрузки React. Пример inline-скрипта (помещать с осторожностью, но он помогает):
Рекомендации зависят от задач. Ниже — список наиболее полезных компонентов shadcn/ui для типичного приложения на Next.js 14 в 2025–2026 годах:
Button — универсальная реализация с поддержкой вариаций через className и Cva. Используйте для основных CTA.
Dialog/Modal — готовые паттерны с управлением фокуса и a11y.
Popover/Tooltip — легковесные подсказки, экономят время при создании интерфейсов.
Tabs/Navigation — для разделения контента без лишнего JS.
Table — базовый рендеринг таблиц; для больших таблиц используйте виртуализацию.
Почему эти компоненты: они минимальны, легко стилизуются через Tailwind/Tokens и не несут лишних runtime-зависимостей. В проектах с высокой нагрузкой предпочтительнее минимальные примитивы: они упрощают tree-shaking и снижают клиентский JS. Для примеров использования посмотрите статьи в разделе Frontend и UI на сайте.
Скриншот переключения dark mode
Частые вопросы
Как 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-фреймворки.
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…