mcpField
C
convex-dev-static-hosting

convex-dev-static-hosting

github.com/growthx-club云与 DevOps0167 次安装5 周前更新
代码仓库

关于 convex-dev-static-hosting

用于从 Convex 存储提供 React 和 Vite 静态资源的 Convex 组件，可将前端与 Convex 后端一同部署，并支持 SPA 回退、资源缓存和旧部署清理。

主要功能

  1. 01从 Convex 存储提供静态文件
  2. 02支持客户端路由的 SPA 回退
  3. 03缓存哈希资源和 HTML
  4. 04通过已认证 CLI 上传资源
  5. 05自动清理旧部署文件

适用场景

  1. 01将 React 前端与 Convex 函数一同部署
  2. 02通过 Convex 部署网址分享原型
  3. 03无需单独托管服务来部署内部仪表盘
  4. 04在有新部署时通知用户

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/growthx-club/build-sprint-skills --skill convex-dev-static-hosting

安装后在 Claude Code 中输入/convex-dev-static-hosting确认已加载。

附带文件UPSTREAM-LICENSE

详细介绍

Agent：在编写使用 Static-Hosting 的代码前，请完整阅读此技能。严格按照安装和配置步骤操作。

Static-Hosting

说明

Static-Hosting 支持开发者直接通过 Convex 提供 React/Vite 应用，无需外部托管服务提供商。它使用 Convex HTTP actions 从 Convex 存储提供文件，并支持客户端路由的自动 SPA 回退、哈希资源的智能缓存，以及旧部署的垃圾回收。上传 API 使用内部函数来确保安全，只有经过身份验证的 CLI 用户才能部署文件。

安装
npm install @convex-dev/static-hosting

当前 npm 版本：@convex-dev/[email protected]

使用场景

  • 使用单一后端部署全栈应用：将 React 前端和 Convex 后端函数托管在同一个部署中，无需使用 Vercel 或 Netlify 等独立托管服务
  • 快速构建原型和演示应用：开发期间跳过外部托管设置，直接通过 Convex 部署 URL 分享可运行的演示
  • 构建内部工具和管理仪表板：通过内置的身份验证集成和零外部依赖，从 Convex 提供公司内部的 React 应用
  • 创建自包含的 SaaS 应用：将整个应用程序栈打包到同时包含后端逻辑和前端资源的 Convex 组件中
  • 实现实时部署通知：使用部署查询钩子，在有新版本可用时通知用户并提示刷新页面

工作原理

该组件通过 registerStaticRoutes() 集成到 Convex 应用配置和 HTTP 路由器中，以从 Convex 存储提供文件。部署期间，CLI 通过 generateUploadUrl() 和 recordAsset() 等内部函数将构建好的资源上传到 Convex 存储。出于安全考虑，这些函数只能通过经过身份验证的 npx convex run 命令访问。

HTTP actions 提供文件时会使用智能缓存——来自 Vite 等打包工具的哈希资源会获得长期缓存标头，而 HTML 文件则使用 ETag 确保内容新鲜。spaFallback 选项会自动为未匹配的路由提供 index.html，从而支持单页应用中的客户端路由。

部署可以使用一次性 deploy 命令：该命令会使用正确的生产环境 VITE_CONVEX_URL 构建前端、部署 Convex 后端，然后上传静态文件；也可以使用单独的 upload 命令以获得更多控制。该组件会自动清理旧部署文件，防止存储膨胀。

不适用场景

  • 针对你的具体使用场景，已有更简单的内置解决方案时
  • 你没有使用 Convex 作为后端时
  • 不需要 Static-Hosting 提供的功能时

资源

评论

支持 Markdown