🚀 React + Vite + Tailwind CSS + Shadcn UI 设置 (vanillaJS)

Source: Dev.to

一个完整的分步指南，帮助你快速搭建 React + Vite + Tailwind CSS + Shadcn UI，并使用简洁的 @/... 别名导入 —— 无需 TypeScript！

⏱️ 完成时间：约 10 分钟
🎯 结果：生产就绪的 React 应用，配备美观且可访问的组件

🧩 Step 1 – 创建 Vite + React 项目

npm create vite@latest my-app
cd my-app

当出现提示时，选择：

✅ Vite 将生成一个精简、快速的 React 入门项目，开箱即支持 HMR（热模块替换）。

🌀 第 2 步 – 安装依赖

npm install
npm install tailwindcss @tailwindcss/vite

🎨 第三步 – 配置 vite.config.js

将 vite.config.js 的全部内容替换为：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import path from "path";

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    tailwindcss(),
    react({
      babel: {
        plugins: [["babel-plugin-react-compiler"]], // ✅ Optional: React Compiler for perf
      },
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"), // ✅ Enable @/ imports
    },
  },
});

为什么这很重要

• @tailwindcss/vite → 在构建时编译 Tailwind（比 PostCSS 更快）。
• @ 别名 → 可以像 import Button from "@/components/ui/button" 这样导入，而无需使用冗长的相对路径。

⚙️ 第4步 – 为编辑器支持添加 jsconfig.json

在项目根目录创建 jsconfig.json：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

好处

• ✅ VS Code 自动补全 @/ 导入
• ✅ ESLint/Prettier 能识别你的别名路径
• ✅ 不再出现 “Cannot find module” 警告

🪄 第5步 – 在 CSS 中导入 Tailwind

打开（或创建）src/index.css 并添加：

@import "tailwindcss";

🎉 使用 @tailwindcss/vite 时，你不需要传统的 @tailwind base; @tailwind components; @tailwind utilities; —— 插件会自动注入它们。

(可选) 删除或清空 src/App.css 以避免默认样式冲突。

🌈 第6步 – 初始化 Shadcn UI

npx shadcn@latest init

添加首批组件：

npx shadcn@latest add button card input

✅ 组件位于 src/components/ui/ 中 —— 完全可定制、可访问，并基于 Tailwind。

💻 第 7 步 – 测试你的设置

将 src/App.jsx 替换为：

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

export default function App() {
  return (
    <div className="p-4">
      <Card>
        <CardHeader>
          <CardTitle>🎉 Setup Successful!</CardTitle>
        </CardHeader>
        <CardContent>
          <p>You're now running React + Vite + Tailwind + Shadcn UI.</p>
          <Button>Click Me</Button>
          <Button variant="secondary">Secondary Action</Button>
        </CardContent>
      </Card>
    </div>
  );
}

启动开发服务器：

npm run dev

访问 http://localhost:5173 —— 你应该能看到一个带有 Shadcn 按钮的精美卡片！

✅ 最终项目结构

my-app/
├── public/
├── src/
│   ├── components/
│   │   └── ui/          # 🎨 Shadcn components (button, card, input…)
│   ├── App.jsx          # 🏠 Main app component
│   ├── index.css        # 🎨 Tailwind import
│   └── main.jsx         # ⚡ React entry point
├── index.html
├── vite.config.js       # ⚙️ Vite + Tailwind + alias config
├── jsconfig.json        # 🧠 Editor alias support
├── tailwind.config.js   # 🎨 Auto‑generated by Shadcn (optional to tweak)
├── package.json
└── …

🧭 小贴士

将所有 Shadcn UI 组件放在 src/components/ui/ 中。这使得在项目增长时，定位、定制和扩展你的设计系统变得更加容易。

📦 项目结构（快速回顾）

• src/ – 您的应用代码
• src/components/ – 自定义可组合组件（例如 UserProfile.jsx、NavBar.jsx）
• src/app/ – Shadcn UI 基元（例如 button.tsx、dialog.tsx）

🛠️ 故障排除快速修复

🧪 奖励：添加暗模式切换（可选）

Shadcn 开箱即支持主题！将以下内容添加到 src/App.jsx：

import { useEffect, useState } from "react";
import { Button } from "@/components/ui/button";

export default function App() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
  }, [dark]);

  return (
    <div className="p-4">
      <Button
        onClick={() => setDark(!dark)}
        variant="outline"
      >
        {dark ? "☀️ Light Mode" : "🌙 Dark Mode"}
      </Button>
    </div>
  );
}

提示： 在 tailwind.config.js 中设置 darkMode: "class"（Shadcn 默认如此）。

🔗 有用资源

• Vite 文档
• Tailwind CSS 文档
• Shadcn UI 文档
• React 编译器（实验性）
• 路径别名最佳实践

🎯 关键要点

• ✅ Vite – 超快的开发服务器和构建工具
• ✅ @tailwindcss/vite – 更简洁的 Tailwind 设置（无需 PostCSS）
• ✅ @/ 别名 – 更清晰、可扩展的导入
• ✅ Shadcn UI – 生产就绪、可访问的组件（代码归你所有）
• ✅ JavaScript 优先 – 快速原型开发无需 TypeScript 负担

🙌 如果本指南帮助你更快交付，请点个 ❤️，与团队分享，或留言告诉我们你在构建什么！