跳过主要内容
文档目录

项目结构

MinuteShip 模板文件和文件夹组织概述

MinuteShip 遵循基于 TanStack Router 文件路由的模块化架构，专注于可扩展性和可维护性。

根目录结构

  • src/
    • api/: API 路由处理器和服务端逻辑
    • auth/: Better Auth 配置和实用程序
    • cache/: 服务端缓存模块
    • components/: 按功能组织的 UI 组件
    • config/: 应用程序的配置文件
    • db/: 数据库 Schema、迁移和实用程序
    • env/: 环境变量验证（客户端/服务端）
    • hooks/: 自定义 React 钩子
    • lib/: 核心应用程序逻辑和实用程序
    • mail/: 邮件模板和发送邮件模块
    • locale/: Paraglide 中间件与生成的运行时代码
    • middlewares/: 路由中间件
    • newsletter/: 邮件列表订阅模块
    • notification/: 通知模块
    • payment/: 支付模块
    • storage/: 文件存储模块
    • routes/: TanStack Router 文件路由
    • types/: TypeScript 类型定义
    • styles.css: 全局样式和 Tailwind CSS 配置
  • content/
    • blog/: Markdown 格式的博客文章
    • pages/: Markdown 格式的自定义页面（法律页面等）
    • changelog/: Markdown 格式的更新日志
  • public/: 从根目录提供的静态资源
  • project.inlang/: 国际化配置与 messages/en.json、messages/zh.json
  • tests/: Vitest 单元测试与 Playwright E2E 测试
  • AGENTS.md: AI 编码助手的项目说明与开发约定
  • scripts/: 实用脚本
  • biome.json: Biome 代码检查和格式化配置
  • content-collections.ts: Content Collections 配置
  • drizzle.config.ts: Drizzle ORM 配置（远程）
  • drizzle.config.local.ts: Drizzle ORM 配置（本地）
  • vitest.config.ts: Vitest unit test configuration
  • playwright.config.ts: Local browser test configuration
  • playwright.production.config.ts: Built Worker smoke test configuration
  • vite.config.ts: Vite 配置
  • wrangler.jsonc: Cloudflare Workers 配置（D1、R2、KV 绑定）

关键文件

  • vite.config.ts：Vite 配置，含 TanStack Start、Cloudflare、Tailwind CSS 和 Content Collections 插件
  • wrangler.jsonc：Cloudflare Workers 配置，包括 D1 数据库、R2 存储和 KV 缓存绑定
  • content-collections.ts：博客、法律条款页面和更新日志的 Content Collections 配置
  • drizzle.config.ts：数据库的 Drizzle ORM 配置
  • biome.json：Biome 代码检查和格式化配置
  • .env.example：环境变量模板

关键目录

/src/api 目录

按功能组织的服务端 API 逻辑：

  • ai.ts: Workers AI and fal.ai server functions
  • contact.ts: 联系表单处理
  • newsletter.ts: 邮件列表订阅逻辑
  • payment.ts: 支付处理逻辑
  • user-files.ts: 用户文件管理逻辑
  • users.ts: 用户管理逻辑

/src/lib 目录

核心应用程序逻辑和实用程序：

  • blog.ts: 博客实用程序
  • changelog.ts: 更新日志实用程序
  • formatter.ts: 数据格式化实用程序
  • markdown.ts: Markdown 处理实用程序
  • pages.ts: 页面实用程序
  • price-plan.ts: 价格计划实用程序
  • routes.ts: 应用程序路由定义
  • seo.ts: SEO 元数据实用程序
  • urls.ts: URL 相关实用程序
  • utils.ts: 通用实用程序

/src/routes 目录

routes 目录遵循 TanStack Router 文件路由约定：

  • __root.tsx: 根布局，包含 Navbar、Footer、ThemeProvider、Analytics 等
  • index.tsx: 首页
  • auth/
    • login.tsx: 登录页面
    • register.tsx: 注册页面
    • forgot-password.tsx: 忘记密码页面
    • reset-password.tsx: 重置密码页面
    • error.tsx: 认证错误页面
  • dashboard/
    • index.tsx: 仪表盘页面
  • settings/
    • index.tsx: 设置首页
    • profile.tsx: 用户资料设置
    • security.tsx: 安全设置
    • billing.tsx: 账单设置
    • payment.tsx: 支付设置
    • notifications.tsx: 通知偏好设置
    • apikeys.tsx: API 密钥管理
    • files.tsx: 文件管理
  • admin/
    • users.tsx: 管理员用户管理
  • (pages)/
    • pricing.tsx: 定价页面
    • about.tsx: 关于页面
    • contact.tsx: 联系页面
    • changelog.tsx: 更新日志页面
    • roadmap.tsx: 路线图页面
    • ai.tsx: AI playground
    • waitlist.tsx: 等待列表页面
  • (legals)/
    • privacy.tsx: 隐私政策
    • terms.tsx: 服务条款
    • cookie.tsx: Cookie 政策
  • blog/
    • index.tsx: 博客列表页面
    • $slug.tsx: 博客文章页面
  • api/
    • auth/
      • $.ts: Better Auth API 处理器
    • webhooks/
      • stripe.ts: Stripe webhook 处理器
      • creem.ts: Creem webhook 处理器
      • waffo.ts: Waffo webhook 处理器
    • storage/
      • file.ts: 文件上传/下载处理器

/src/components 目录

组件按功能和用途组织，以便更好地维护：

共享组件

共享组件在整个应用程序中可重用，并在专用目录中组织：

  • ui/: Shadcn UI 组件，如按钮、输入等
  • blocks/: 营销页面区块（首页、功能等）
  • layout/: 布局组件，如导航栏、页脚等
  • shared/: 其他共享组件
  • theme/: 主题提供者和切换
  • analytics/: 统计分析组件
  • chatbox/: 在线客服组件（Crisp）

功能模块的组件

组件目录按功能组织，便于定位和维护与特定功能相关的组件，如身份验证、博客、仪表盘等。

  • admin/: 管理员面板组件
  • auth/: 身份验证相关组件
  • blog/: 博客相关组件
  • changelog/: 更新日志相关组件
  • contact/: 联系相关组件
  • dashboard/: 仪表盘相关组件
  • payment/: 支付相关组件
  • pricing/: 定价相关组件
  • settings/: 用户设置相关组件
  • waitlist/: 等待列表相关组件

下一步

现在您了解了项目结构，探索这些相关主题：