# react-tailwind-vite-shadcn

**Repository Path**: functioncat-templates/react-tailwind-vite-shadcn

## Basic Information

- **Project Name**: react-tailwind-vite-shadcn
- **Description**: 一个React, TailwindCSS, Vite, ShadcnUI 的模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 56
- **Created**: 2025-09-14
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Funcate 启动模板

一个为 Funcate 平台设计的基础启动项目模板，内置身份验证和用户管理功能。此模板提供了大多数应用程序所需的基础设施，使用现代 React、Tailwind CSS、Shadcn UI 作为前端应用技术栈 和 Vite 构建，并集成 Funcate 平台的 Bearer 认证和 LiteDB 数据库服务

## 🚀 功能特性

### 🔐 身份验证
- **Bearer 身份验证** 与 Funcate 平台集成
- **用户注册与登录** 使用 JWT 令牌
- **令牌刷新** 实现无缝会话管理
- **受保护路由** 基于身份验证状态

### 🗄️ 数据库
- **LiteDB 服务** 与 Funcate 平台集成
- **简单用户管理** (id, name, created_at, updated_at)
- **API 规则** 用于安全的数据访问控制
- **数据库迁移** 用于模式管理

### 🔧 开发工具
- **SWR 数据获取** - 用于远程数据的 React hooks
- **模块化组件** - 易于定制或移除
- **TypeScript** - 完整的类型安全
- **Tailwind CSS** - 实用优先的样式
- **Shadcn UI** - 美观、可访问的组件
- **Vite** - 快速开发和构建

## 📁 项目结构

```
.
├── src/
│   ├── components/           # React 组件
│   │   ├── ui/              # Shadcn UI 组件
│   │   ├── login-form.tsx   # 模块化登录组件
│   │   └── register-form.tsx # 模块化注册组件
│   ├── hooks/               # 自定义 React hooks
│   │   ├── useApi.ts        # 使用 SWR 的通用 API hooks
│   │   ├── useAuth.ts       # 身份验证 hooks
│   │   └── useUsers.ts      # 用户数据管理 hooks
│   ├── App.tsx              # 主应用组件
│   ├── main.tsx             # 应用入口点
│   └── index.css            # 全局样式
├── db/
│   ├── migrations/          # 数据库迁移文件
│   └── rules.json           # LiteDB API 访问规则
├── funcate.yaml         # Funcate 部署配置
├── package.json             # 依赖项和脚本
└── README.md                # 本文档
```

## 🚀 快速开始

### 前提条件
- Node.js 18+ 
- npm 或 yarn 包管理器

### 安装步骤

1. **安装依赖项**
   ```bash
   npm install
   ```

2. **设置环境变量**
   ```bash
   cp .env.example .env
   ```
   `VITE_FUNCATE_ENV_URL` 将在 Funcate 部署期间自动设置。

3. **启动开发服务器**
   ```bash
   npm run dev
   ```
   开发服务器将在 http://localhost:5173 启动

4. **构建生产版本**
   ```bash
   npm run build
   ```

## 📋 可用脚本

- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm run preview` - 预览生产构建
- `npm run type-check` - 运行 TypeScript 类型检查

## 🔐 身份验证流程

### 用户注册
1. 用户输入显示名称、邮箱（作为用户名）和密码
2. 系统在 Funcate bearer auth 中创建用户
3. 注册后用户自动登录

### 用户登录
1. 用户输入用户名和密码
2. 系统通过 Funcate bearer auth 进行身份验证
3. JWT 令牌被存储用于后续 API 调用

### 令牌管理
- 令牌在过期前自动刷新
- 身份验证状态在页面重新加载时保持
- 退出登录清除所有身份验证数据

## 🗄️ 数据库模式

### 用户表
```sql
CREATE TABLE users (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### API 规则
访问控制定义在 `db/rules.json` 中：
- 用户只能访问自己的数据
- 所有操作都需要身份验证
- 不允许对用户数据进行公共访问

## 🎨 定制化

### 添加新功能
1. **新组件** - 添加到 `src/components/`
2. **新 Hooks** - 添加到 `src/hooks/`
3. **新 API 端点** - 扩展 `useApi.ts` hook
4. **新数据库表** - 添加迁移文件到 `db/migrations/`

### 移除身份验证
如果您的项目不需要身份验证：
1. 移除 `src/components/login-form.tsx` 和 `src/components/register-form.tsx`
2. 移除 `src/hooks/useAuth.ts` 并更新 `src/hooks/useUsers.ts`
3. 更新 `src/App.tsx` 移除身份验证相关 UI
4. 更新 `funcate.yaml` 移除不需要的 auth 

### 样式定制
- 编辑 `src/index.css` 修改全局样式
- 使用 Tailwind CSS 类进行组件样式设计
- 根据需要定制 Shadcn UI 组件

## 🌐 部署

### Funcate 平台
此模板配置为在 Funcate 上无缝部署：

1. **自动部署** - 推送到主分支触发部署
2. **环境变量** - 自动注入
3. **数据库配置** - 带迁移的 LiteDB
4. **身份验证服务** - 配置好的 Bearer auth

### 配置
`funcate.yaml` 文件定义：
- 前端应用构建设置
- 带迁移的 LiteDB 服务
- Bearer 身份验证
- 生产环境配置


## 🔧 开发指南

### 添加 Shadcn UI 组件
```bash
npx shadcn-ui@latest add [组件名称]
```

### TypeScript
- 所有组件都使用 TypeScript 编写
- 为所有 hooks 提供类型定义
- 可以根据需要添加自定义类型

### 代码组织
- **组件** 模块化且可重用
- **Hooks** 封装业务逻辑
- **样式** 使用 Tailwind CSS 实用类
- **配置** 与代码分离

## 📦 依赖项

### 核心依赖
- `react` & `react-dom` - UI 框架
- `typescript` - 类型安全
- `tailwindcss` - 样式
- `shadcn/ui` - 组件库
- `vite` - 构建工具
- `swr` - 数据获取

### 开发依赖
- `@types/*` - 类型定义
- `@vitejs/plugin-react` - Vite 的 React 支持
- `autoprefixer` & `postcss` - CSS 处理

## 🛠️ 故障排除

### 常见问题

1. **身份验证错误**
   - 检查 Funcate 环境 URL
   - 验证 bearer auth 是否已部署
   - 检查浏览器控制台获取详细错误信息

2. **数据库错误**
   - 验证迁移是否已运行
   - 检查 API 规则配置
   - 确保正确的身份验证令牌

3. **构建错误**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

## 📄 许可证

此模板是开源的，可在 MIT 许可证下使用。

## 🤝 贡献

欢迎贡献！请随时提交问题和拉取请求。

---

**开始在 Funcate 上构建您的下一个伟大项目！** 🚀