web-app

基于 Hono + Vite + React 的全栈模板，目标是在保留前端开发体验的同时，提供更轻量的 Node 运行时方案。

技术栈

• 前端：React 19、React Router、Tailwind CSS v4、shadcn/ui、React Query
• 后端：Hono（Node runtime）
• 数据层：TypeORM（默认 sqlite，支持切换 postgres）
• 契约校验：Zod（shared/contracts/routes.ts，兼容 shared/routes.ts re-export）

目录结构

.
├── .imagicma/
│   ├── AGENTS.md                 # 运行/修改约束补充说明
│   └── runtime.env               # 项目运行端口契约，仅使用大写 PORT
├── client/
│   ├── index.html                # Vite 前端入口 HTML
│   ├── public/                   # 前端静态资源
│   └── src/
│       ├── App.tsx               # 前端应用根组件
│       ├── main.tsx              # 前端挂载入口
│       ├── globals.css           # 全局样式与设计 token
│       ├── components/           # 页面级与基础组件
│       │   └── ui/               # shadcn/ui 组件
│       ├── hooks/                # 客户端 hooks
│       ├── lib/                  # 前端通用工具与预览桥接逻辑
│       └── pages/                # 路由页面
├── server/
│   ├── app.ts                    # Hono 装配入口，仅注册 middleware、routes、静态资源
│   ├── dev-app.ts                # 开发态 server 入口
│   ├── index.ts                  # 生产态 server 入口
│   ├── controllers/             # HTTP 适配层，解析请求并返回响应
│   ├── db/                      # DataSource 与数据库配置
│   ├── middlewares/             # 日志、异常等横切能力
│   ├── models/
│   │   ├── entities/            # TypeORM entity 等持久化模型
│   │   ├── repositories/        # 数据访问实现
│   │   ├── services/            # 业务规则与编排
│   │   └── types/               # 仅服务端内部使用的类型
│   └── routes/                  # 路由绑定层，只做 URL 到 controller 的映射
├── shared/
│   ├── constants/               # 前后端共享纯常量
│   ├── contracts/               # 前后端共享 API path 与 Zod 契约
│   ├── routes.ts                # contracts 的兼容 re-export
│   ├── schema.ts                # 共享 schema 聚合导出
│   └── types/                   # 前后端共享纯 TypeScript 类型
├── scripts/                     # 受保护的启动/守卫脚本
├── .env.example                 # 环境变量示例
├── package.json
├── tsconfig.json
├── tsconfig.server.json
└── vite.config.ts

分层约束

• server/routes 只能依赖 controllers
• server/controllers 只负责 HTTP 适配，依赖 models 与 shared
• server/models/repositories 只负责数据读写，不返回 HTTP 响应结构
• server/models/services 负责业务规则、聚合与默认值，不接触 Hono Context
• shared/ 只能放前后端都能安全复用的契约、常量和纯类型，禁止放 TypeORM entity、Node API、Hono 运行时代码

常用命令

pnpm install
pnpm dev
pnpm build
pnpm start
pnpm check
pnpm lint

• pnpm dev：本地开发，使用受保护脚本拉起 Vite + Hono
• pnpm build：构建前端并编译服务端
• pnpm start：以生产模式启动构建产物
• pnpm check：执行前后端 TypeScript 类型检查
• pnpm lint：执行 ESLint

如果你是在 imagicma 的 agent/workflow 环境中维护该模板，请继续遵循 AGENTS.md 的约束，通过工作流提供的启动入口执行，不要绕过 scripts/ 里的受保护脚本。

端口与运行时文件

启动时按以下顺序解析端口：

1. 显式环境变量 PORT
2. 项目内 .imagicma/runtime.env

如果两者都不存在，启动会直接失败。.imagicma/runtime.env 示例：

PORT=6424

构建产物

• 前端产物：dist/client
• 后端产物：dist/server
• 发布产物：artifacts/release

生产启动时由 Hono 同时承载 API、静态资源与 SPA fallback。

发布目录

执行 pnpm build 后，除了常规 dist/ 编译产物，还会生成可分发目录 artifacts/release。

该目录包含：

• dist/client、dist/server、dist/shared
• .data/app.db
• 所有 .env* 文件
• 初始化脚本：init.sh
• 启动脚本：start.sh

建议的发布用法：

cd artifacts/release
./init.sh 5011
npm start

数据库

服务启动时会自动同步当前示例表结构。

• 默认数据库：DB_TYPE=sqlite
• 默认数据库文件：./.data/app.db
• 自定义 SQLite 路径：复制 .env.example 为 .env.local 后设置 DATABASE_FILE
• 切换 Postgres：
  • DB_TYPE=postgres
  • DATABASE_URL=postgres://user:pass@host:5432/dbname

数据库类型建议在项目首次启动前确定；初始化后默认按固定配置处理，不承诺无损切换。

验证路径

• API：GET /api/greeting
• 页面：/