fenghuo/README.md

[![GitHub][opengraph-image]][opengraph-image-url]

# shadcn/ui and tailwindcss v4 monorepo template

This template is for creating a monorepo with Turborepo, shadcn/ui, tailwindcss v4, and react v19.

## 项目结构

```
├── apps/
│   ├── backend/          # Hono 后端应用
│   └── web/              # Next.js 前端应用
├── packages/
│   ├── db/               # Prisma 数据库包
│   ├── storage/          # 存储解决方案包
│   ├── tus/              # TUS 上传协议包
│   └── ui/               # UI 组件包
└── docs/                 # 文档
```

## 特性

- 🚀 **现代技术栈**: Next.js 15, React 19, Hono, Prisma
- 📦 **Monorepo**: 使用 Turborepo 管理多包项目
- 🎨 **UI 组件**: shadcn/ui + TailwindCSS v4
- 📤 **文件上传**: 支持 TUS 协议的可恢复上传
- 💾 **多存储支持**: 本地存储 + S3 兼容存储
- 🗄️ **数据库**: PostgreSQL + Prisma ORM
- 🔄 **实时通信**: WebSocket 支持

## 快速开始

### 1. 安装依赖

```bash
pnpm install
```

### 2. 环境变量配置

复制环境变量模板并配置：

```bash
cp .env.example .env
```

#### 存储配置

**本地存储（开发环境推荐）:**

```bash
STORAGE_TYPE=local
UPLOAD_DIR=./uploads
```

**S3 存储（生产环境推荐）:**

```bash
STORAGE_TYPE=s3
S3_BUCKET=your-bucket-name
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
```

**MinIO 本地开发:**

```bash
STORAGE_TYPE=s3
S3_BUCKET=uploads
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_FORCE_PATH_STYLE=true
```

详细的环境变量配置请参考：[环境变量配置指南](./docs/ENVIRONMENT.md)

### 3. 数据库设置

```bash
# 生成 Prisma 客户端
pnpm db:generate

# 运行数据库迁移
pnpm db:migrate

# 填充种子数据（可选）
pnpm db:seed
```

### 4. 启动开发服务器

```bash
pnpm dev
```

这将启动：

- 前端应用: http://localhost:3001
- 后端 API: http://localhost:3000
- 文件上传: http://localhost:3000/upload
- 存储管理 API: http://localhost:3000/api/storage

## 存储包 (@repo/storage)

项目包含一个功能完整的存储解决方案包，支持：

### 核心功能

- 🗂️ **多存储后端**: 本地文件系统、AWS S3、MinIO、阿里云 OSS、腾讯云 COS
- 📤 **TUS 上传**: 支持可恢复的大文件上传
- 🔧 **Hono 集成**: 提供即插即用的中间件
- 📊 **文件管理**: 完整的文件生命周期管理
- ⏰ **自动清理**: 过期文件自动清理机制
- 🔄 **存储迁移**: 支持不同存储类型间的数据迁移

### API 端点

```bash
# 文件资源管理
GET    /api/storage/resources              # 获取所有资源
GET    /api/storage/resource/:fileId       # 获取文件信息
DELETE /api/storage/resource/:id           # 删除资源

# 文件访问和下载
GET    /download/:fileId                   # 文件下载和访问（支持所有存储类型）

# 统计和管理
GET    /api/storage/stats                  # 获取统计信息
POST   /api/storage/cleanup                # 清理过期文件
POST   /api/storage/migrate-storage        # 迁移存储类型

# 文件上传 (TUS 协议)
POST   /upload                             # 开始上传
PATCH  /upload/:id                         # 续传文件
HEAD   /upload/:id                         # 获取上传状态
```

### 使用示例

```typescript
import { createStorageApp, startCleanupScheduler } from '@repo/storage';

// 创建存储应用
const storageApp = createStorageApp({
	apiBasePath: '/api/storage',
	uploadPath: '/upload',
});

// 挂载到主应用
app.route('/', storageApp);

// 启动清理调度器
startCleanupScheduler();
```

## One-click Deploy

You can deploy this template to Vercel with the button below:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?build-command=cd+..%2F..%2F+%26%26+pnpm+turbo+build+--filter%3Dweb...&demo-description=This+is+a+template+Turborepo+with+ShadcnUI+tailwindv4&demo-image=%2F%2Fimages.ctfassets.net%2Fe5382hct74si%2F2JxNyYATuuV7WPuJ31kF9Q%2F433990aa4c8e7524a9095682fb08f0b1%2FBasic.png&demo-title=Turborepo+%26+Next.js+Starter&demo-url=https%3A%2F%2Fexamples-basic-web.vercel.sh%2F&from=templates&project-name=Turborepo+%26+Next.js+Starter&repository-name=turborepo-shadcn-tailwind&repository-url=https%3A%2F%2Flinkb15%2Fturborepo-shadcn-ui-tailwind-4&root-directory=apps%2Fweb&skippable-integrations=1)

## 添加 UI 组件

To add components to your app, run the following command at the root of your `web` app:

```bash
pnpm dlx shadcn@latest add button -c apps/web
```

This will place the ui components in the `packages/ui/src/components` directory.

## Tailwind

Your `globals.css` are already set up to use the components from the `ui` package which is imported in the `web` app.

## 使用组件

To use the components in your app, import them from the `ui` package.

```tsx
import { Button } from '@repo/ui/components/ui/button';
```

## 脚本命令

```bash
# 开发
pnpm dev                    # 启动所有应用
pnpm dev:web               # 只启动前端
pnpm dev:backend           # 只启动后端

# 构建
pnpm build                 # 构建所有包
pnpm build:web             # 构建前端
pnpm build:backend         # 构建后端

# 数据库
pnpm db:generate          # 运行数据库迁移
pnpm db:seed               # 填充种子数据
pnpm db:studio             # 打开 Prisma Studio

# 代码质量
pnpm lint                  # 代码检查
pnpm type-check            # 类型检查
pnpm format                # 代码格式化
```

## 文档

- [环境变量配置指南](./docs/ENVIRONMENT.md)
- [存储包文档](./packages/storage/README.md)
- [文件访问使用指南](./docs/STATIC_FILES.md)

## More Resources

- [shadcn/ui - Monorepo](https://ui.shadcn.com/docs/monorepo)
- [Turborepo - shadcn/ui](https://turbo.build/repo/docs/guides/tools/shadcn-ui)
- [TailwindCSS v4 - Explicitly Registering Sources](https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources)
- [Hono Documentation](https://hono.dev/)
- [TUS Protocol](https://tus.io/)

[opengraph-image]: https://turborepo-shadcn-tailwind.vercel.app/opengraph-image.png
[opengraph-image-url]: https://turborepo-shadcn-tailwind.vercel.app/