Урок 17. Частые ошибки установки

📁 Раздел: shadcn/ui ⏱️ Время изучения: ~50 мин 🎯 Сложность: Средняя

⚡ Кратко

Алиас настроен наполовину, CSS не импортирован, установка поверх Tailwind v3, перезапись собственных правок.

Ошибка 1. Алиас только в одном месте

Как ломается: сборка проходит, но редактор подчёркивает @/lib/utils красным. Или наоборот: редактор доволен, а сборка падает.

✅ Настраиваем оба файла

📄 vite.config.ts

// vite.config.ts
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})

📄 tsconfig.json

// tsconfig.json — и то же самое в tsconfig.app.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

В шаблоне Vite не забудьте про tsconfig.app.json — именно он отвечает за код приложения.

Ошибка 2. CSS не импортирован в приложение

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

// src/main.tsx
import "./index.css"   // ← без этой строки токены темы не попадут на страницу

Ошибка 3. Установка поверх Tailwind v3

Как ломается: CLI пишет, что нашёл v3, и предлагает другой набор действий; либо компоненты добавляются, но оформление «плывёт», потому что токены заданы в другом формате.

Как правильно: сначала обновите Tailwind до v4 (см. справочник по миграции), затем ставьте shadcn/ui.

Ошибка 4. add --overwrite поверх своих правок

Как ломается: вы добавили в кнопку фирменный вариант, повторно выполнили add button --overwrite и потеряли изменения.

git status                                 # рабочее дерево должно быть чистым
npx shadcn@latest add button --diff        # что отличается
npx shadcn@latest add button --overwrite   # и только потом перезапись

Ошибка 5. Пропущенный @types/node

Как ломается: TypeScript ругается на path и __dirname в vite.config.ts.

npm install -D @types/node

Ошибка 6. Смешение реестров и версий

Компонент, скопированный из статьи под Radix, рядом с компонентами на Base UI — источник трудноуловимых ошибок: разные пропсы полиморфизма, разные имена состояний в атрибутах. Если нужен Radix, выберите его для всего проекта флагом --base radix при инициализации.

Диагностика: с чего начинать

npx shadcn@latest info    # что CLI видит в проекте

Команда покажет фреймворк, версию Tailwind, путь к CSS и алиасы. Если что-то определено неверно — проблема в конфигурации проекта, а не в реестре.