Turborepo + Vite + Next.js + Shadcn Monorepo 项目构建

从零开始构建 Turborepo + Vite + Next.js + Shadcn 的 Monorepo 项目的完整流程。构建一个现代、高性能的 Web 系统，包含：

• 多个前端应用（Next.js 和 Vite 都支持）
• 可共享的 UI 组件库（使用 shadcn/ui）
• 高效的构建与缓存支持（通过 Turborepo）
• 使用 pnpm 管理依赖

---

🧱 最终结构预览

my-monorepo/
├── apps/
│   ├── web/         # Next.js 应用
│   └── docs/        # Vite 应用（文档或营销页）
├── packages/
│   └── ui/          # 共用 UI 组件库，shadcn/ui
├── turbo.json       # Turborepo 配置
├── pnpm-workspace.yaml
├── tsconfig.json
└── package.json     # 根目录 package.json

---

🛠️ 步骤一：初始化项目

mkdir my-monorepo && cd my-monorepo
pnpm init -y

安装必要的依赖：

pnpm add -D turbo typescript

创建 pnpm-workspace.yaml：

# pnpm-workspace.yaml
packages:
  - apps/*
  - packages/*

---

✨ 步骤二：初始化 Turborepo 配置

创建 turbo.json：

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {}
  }
}

---

🧱 步骤三：添加 Next.js 应用（web）

cd my-monorepo
pnpm create next-app apps/web --typescript --app

进入 apps/web，安装依赖：

cd apps/web
pnpm install

---

🔥 步骤四：安装 shadcn/ui 到 web 应用中

cd apps/web
npx shadcn-ui@latest init

使用默认配置（选择 Tailwind、TypeScript、默认路径），会自动创建好 components/ui 和 tailwind.config.ts。

---

📘 步骤五：添加 Vite 应用（docs）

cd ../../
pnpm create vite apps/docs --template react-ts
cd apps/docs
pnpm install

然后配置 TailwindCSS：

pnpm add -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

修改 tailwind.config.js：

// apps/docs/tailwind.config.js
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "../../packages/ui/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {}
  },
  plugins: []
}

在 src/index.css 中加入：

@tailwind base;
@tailwind components;
@tailwind utilities;

---

🧩 步骤六：创建共享 UI 组件库（packages/ui）

mkdir -p packages/ui/src
cd packages/ui
pnpm init -y

安装 React + Tailwind 相关依赖：

pnpm add react react-dom
pnpm add -D typescript tailwindcss postcss autoprefixer

初始化 tsconfig.json：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "jsx": "react-jsx",
    "declaration": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "Node",
    "baseUrl": ".",
    "paths": {}
  },
  "include": ["src"]
}

创建一个组件：

// packages/ui/src/button.tsx
import { ButtonHTMLAttributes } from "react"

export function Button(props: ButtonHTMLAttributes<HTMLButtonElement>) {
  return (
    <button
      className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
      {...props}
    />
  )
}

packages/ui/package.json 添加：

{
  "name": "ui",
  "main": "./src/index.ts",
  "type": "module"
}

---

🧩 步骤七：在 web/docs 中使用 packages/ui

安装本地依赖：

# 根目录执行
pnpm add ui --workspace --filter web
pnpm add ui --workspace --filter docs

然后在 apps/web 和 apps/docs 中都可以引入：

import { Button } from "ui"

---

🧪 步骤八：配置 TypeScript 共享设置（可选）

根目录 tsconfig.json：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "ui": ["packages/ui/src"]
    }
  }
}

然后在 apps/web/tsconfig.json 中使用：

{
  "extends": "../../tsconfig.json"
}

---

🚀 步骤九：运行开发环境

# 运行 Next.js 应用
pnpm dev --filter web

# 运行 Vite 应用
pnpm dev --filter docs

---

✅ 总结

Monorepo 架构，特点如下：

特性	技术栈
Monorepo 构建工具	Turborepo
包管理器	pnpm + workspace
主站应用（App Router）	Next.js + TypeScript
文档/营销页	Vite + React
UI 组件库	packages/ui + shadcn/ui
样式	Tailwind CSS
构建缓存与依赖追踪	Turbo pipeline