Getting started
项目结构
了解 vibetake 的目录结构和文件组织
项目结构
vibetake 采用现代化的目录结构设计，遵循 Next.js 13+ App Router 的最佳实践，同时保持代码的清晰性和可维护性。本文档将详细介绍每个目录和文件的用途。
📁 根目录结构
vibetake/
├── 📁 .kiro/ # Kiro AI 配置目录
├── 📁 .next/ # Next.js 构建输出（自动生成）
├── 📁 .source/ # Fumadocs 源配置
├── 📁 .trae/ # Trae 规则配置
├── 📁 .vscode/ # VS Code 工作区配置
├── 📁 content/ # 文档和内容文件
├── 📁 drizzle/ # 数据库迁移文件
├── 📁 node_modules/ # 依赖包（自动生成）
├── 📁 public/ # 静态资源文件
├── 📁 script/ # 脚本文件
├── 📁 src/ # 源代码目录
├── 📄 .env.example # 环境变量模板
├── 📄 .gitignore # Git 忽略文件
├── 📄 biome.json # Biome 配置
├── 📄 components.json # shadcn/ui 组件配置
├── 📄 drizzle.config.ts # Drizzle ORM 配置
├── 📄 next.config.ts # Next.js 配置
├── 📄 package.json # 项目依赖和脚本
├── 📄 postcss.config.mjs # PostCSS 配置
├── 📄 README.md # 项目说明文档
├── 📄 source.config.ts # Fumadocs 配置
├── 📄 tailwind.config.js # Tailwind CSS 配置
└── 📄 tsconfig.json # TypeScript 配置🎯 核心目录详解
📁 src/ - 源代码目录
这是项目的核心代码目录，采用 Next.js App Router 结构：
src/
├── 📁 app/ # Next.js App Router 页面
│ ├── 📁 admin/ # 管理后台页面
│ │ ├── 📁 accounts/ # 账户管理
│ │ ├── 📁 sessions/ # 会话管理
│ │ ├── 📁 users/ # 用户管理
│ │ ├── 📁 verifications/ # 验证管理
│ │ └── 📄 page.tsx # 管理首页
│ ├── 📁 api/ # API 路由
│ │ ├── 📁 auth/ # 认证相关 API
│ │ └── 📁 search/ # 搜索 API
│ ├── 📁 docs/ # 文档页面
│ │ ├── 📁 [[...slug]]/ # 动态文档路由
│ │ └── 📄 layout.tsx # 文档布局
│ ├── 📁 login/ # 登录页面
│ ├── 📁 register/ # 注册页面
│ ├── 📄 globals.css # 全局样式
│ ├── 📄 layout.tsx # 根布局组件
│ └── 📄 page.tsx # 首页组件
├── 📁 components/ # React 组件库
│ ├── 📁 docs/ # 文档相关组件
│ ├── 📁 page/ # 页面级组件
│ ├── 📁 sections/ # 页面区块组件
│ └── 📁 ui/ # 基础 UI 组件
├── 📁 hooks/ # 自定义 React Hooks
├── 📁 lib/ # 工具库和配置
├── 📁 page/ # 页面相关文件（预留）
├── 📁 services/ # 服务层
│ ├── 📁 ai/ # AI 服务（预留）
│ ├── 📁 database/ # 数据库服务
│ ├── 📁 payment/ # 支付服务（预留）
│ └── 📁 userauth/ # 用户认证服务
└── 📁 styles/ # 样式文件
├── 📄 globals.css # 全局样式
└── 📄 theme.css # 主题样式📁 content/ - 内容目录
存放文档和博客内容，使用 MDX 格式：
content/
├── 📁 blogs/ # 博客文章（预留）
└── 📁 docs/ # 文档内容
├── 📁 api/ # API 文档
├── 📁 components/ # 组件文档
├── 📁 frameworks/ # 框架集成文档
├── 📁 getting-started/ # 快速开始文档
├── 📄 index.mdx # 文档首页
└── 📄 installation.mdx # 安装指南📁 public/ - 静态资源
存放静态文件，可直接通过 URL 访问：
public/
├── 📁 _convertfast/ # ConvertFast 相关资源
├── 📄 favicon.svg # 网站图标
├── 📄 icon-black.svg # 黑色主题图标
├── 📄 icon-white.svg # 白色主题图标
├── 📄 icon.png # PNG 格式图标
└── 📄 icon.svg # SVG 格式图标🔧 配置文件详解
核心配置文件
| 文件 | 用途 | 说明 |
|---|---|---|
next.config.ts | Next.js 配置 | 构建、路由、插件配置 |
tailwind.config.js | Tailwind CSS 配置 | 样式、主题、插件配置 |
tsconfig.json | TypeScript 配置 | 类型检查、编译选项 |
drizzle.config.ts | 数据库配置 | ORM、迁移、连接配置 |
source.config.ts | Fumadocs 配置 | 文档生成、导航配置 |
开发工具配置
| 文件 | 用途 | 说明 |
|---|---|---|
biome.json | 代码格式化 | Lint、格式化规则 |
components.json | shadcn/ui 配置 | 组件库配置 |
postcss.config.mjs | PostCSS 配置 | CSS 处理配置 |
.env.example | 环境变量模板 | 环境配置示例 |
📦 组件架构
UI 组件层次结构
components/
├── 📁 ui/ # 基础 UI 组件（shadcn/ui）
│ ├── 📄 button.tsx # 按钮组件
│ ├── 📄 input.tsx # 输入框组件
│ ├── 📄 card.tsx # 卡片组件
│ └── ... # 其他基础组件
├── 📁 sections/ # 页面区块组件
│ ├── 📄 navbar.tsx # 导航栏
│ ├── 📄 hero-section.tsx # 英雄区块
│ ├── 📄 footer.tsx # 页脚
│ └── ... # 其他区块组件
├── 📁 page/ # 页面级组件
│ ├── 📄 login-form.tsx # 登录表单
│ └── 📄 register-form.tsx # 注册表单
└── 📁 docs/ # 文档相关组件
└── 📄 mdx-components.tsx # MDX 自定义组件组件设计原则
- 原子化设计 - 从小到大构建组件
- 可复用性 - 组件应该易于复用
- 类型安全 - 使用 TypeScript 确保类型安全
- 可访问性 - 遵循 WCAG 可访问性标准
🗄️ 数据库架构
数据库文件结构
drizzle/
├── 📁 meta/ # 迁移元数据
│ ├── 📄 0000_snapshot.json # 数据库快照
│ └── 📄 _journal.json # 迁移日志
├── 📁 postgres/ # PostgreSQL 迁移（可选）
└── 📄 0000_wide_warlock.sql # SQLite 迁移文件数据库模式
// src/services/database/schema.ts
export const users = sqliteTable('users', {
id: text('id').primaryKey(),
email: text('email').notNull().unique(),
name: text('name'),
// ... 其他字段
});🔐 认证系统架构
认证服务结构
src/services/userauth/
├── 📄 auth.ts # BetterAuth 配置
└── 📄 auth-client.ts # 客户端认证工具认证流程
- 用户注册 - 创建新用户账户
- 邮箱验证 - 验证用户邮箱
- 登录认证 - 用户身份验证
- 会话管理 - 维护用户会话
- 权限控制 - 基于角色的访问控制
📚 文档系统架构
Fumadocs 配置
// source.config.ts
export const docs = defineDocs({
dir: "content/docs",
// 文档配置选项
});文档组织原则
- 层次化结构 - 清晰的目录层次
- 导航友好 - 易于导航和搜索
- 内容丰富 - 详细的使用说明和示例
- 多语言支持 - 支持中英文双语
🎨 样式系统架构
Tailwind CSS 配置
// tailwind.config.js
module.exports = {
content: [
'./src/**/*.{js,ts,jsx,tsx,mdx}',
'./content/**/*.{md,mdx}',
],
theme: {
extend: {
// 自定义主题配置
},
},
plugins: [
// Tailwind 插件
],
}样式组织
- 全局样式 -
src/styles/globals.css - 主题样式 -
src/styles/theme.css - 组件样式 - 使用 Tailwind 类名
- 响应式设计 - 移动优先的响应式布局
🛠️ 开发工具集成
VS Code 配置
// .vscode/settings.json
{
"typescript.preferences.importModuleSpecifier": "relative",
"editor.formatOnSave": true,
"editor.defaultFormatter": "biomejs.biome"
}推荐扩展
- Biome - 代码格式化和 Lint
- Tailwind CSS IntelliSense - Tailwind 智能提示
- TypeScript Importer - 自动导入类型
- MDX - MDX 文件支持
📋 最佳实践
文件命名规范
- 组件文件 - 使用 PascalCase:
UserProfile.tsx - 工具文件 - 使用 camelCase:
formatDate.ts - 页面文件 - 使用 kebab-case:
user-profile.tsx - 常量文件 - 使用 UPPER_CASE:
API_ENDPOINTS.ts
目录组织原则
- 功能分组 - 按功能而非文件类型分组
- 就近原则 - 相关文件放在一起
- 扁平化 - 避免过深的目录嵌套
- 一致性 - 保持命名和结构的一致性
代码组织建议
// 推荐的导入顺序
import React from 'react'; // 1. React 相关
import { NextPage } from 'next'; // 2. Next.js 相关
import { Button } from '@/components/ui'; // 3. 内部组件
import { formatDate } from '@/lib/utils'; // 4. 工具函数
import type { User } from '@/types'; // 5. 类型定义🔄 扩展指南
添加新页面
- 在
src/app/下创建目录 - 添加
page.tsx文件 - 可选添加
layout.tsx布局 - 更新导航配置
添加新组件
- 在适当的
components/子目录下创建 - 使用 TypeScript 定义 Props 接口
- 添加 JSDoc 注释
- 导出组件和类型
添加新 API
- 在
src/app/api/下创建路由 - 实现 HTTP 方法处理函数
- 添加类型定义和验证
- 更新 API 文档
这个项目结构设计旨在提供清晰的代码组织、良好的开发体验和易于维护的代码库。遵循这些约定将帮助你构建高质量的应用程序。