Communitygithub.com

five-angles-company/convex-starter

用于 Astro 落地页(Landing Page)的开发:编辑营销站点、添加区块/组件、使用 shadcn/@workspace/ui、Tailwind v4 样式以及添加动态数据。涵盖了零 JS 模式、针对 .astro 文件的 Tailwind @source 修复以及 Convex 静态站点模式。

convex-starter 是什么?

该技能专注于 Astro 静态营销站点(`apps/landing`)的开发与维护。它明确了该站点遵循零客户端 JS 的模型,即使用 shadcn 组件时默认不发送任何 JS,除非显式添加 `client:*` 指令。技能文档特别强调了 Tailwind v4 的关键配置修复:由于共享的 `@workspace/ui/globals.css` 默认只扫描 `.ts/.tsx` 文件,必须在项目 CSS 中添加 `@source "./**/*.{astro,ts,tsx}"`,以确保 `.astro` 文件中的工具类能被正确生成。此外,它还描述了如何使用 Convex HTTP 客户端(`ConvexHttpClient`)为静态站点添加动态数据,以及规避 CSS 注释中包含 `**/` 导致的解析陷阱。此技能适用于所有需要修改落地页的开发者,包括编辑组件、样式、或引入动态交互逻辑。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/five-angles-company/convex-starter/tree/HEAD/.claude/skills/astro-landing

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Landing (Astro)

apps/landing 是一个静态 Astro 站点,它复用 @workspace/ui(shadcn / Tailwind v4)来保持品牌一致性,并且几乎不引入客户端 JS。

使用场景

  • 对 apps/landing 的任何修改:区块、组件、样式或添加动态数据。

禁止使用场景

  • Next.js 应用或移动端 — 运行环境不同。

零-JS 模型

  • Astro 默认在构建时将 React 组件渲染为静态 HTML。使用 shadcn 组件(如 <Button>、<Card>、<Badge>)进行展示时,不会发送任何客户端 JS。
  • 只有在你添加 client:* 指令(如 client:load、client:visible)时才会发送 JS。请仅将其用于真正需要交互的片段,并将这些交互组件放在**单个 .tsx 孤岛(island)**中 — React 上下文不会在多个 Astro 孤岛之间共享。
  • 对于需要按钮样式的链接,优先使用 <a class={buttonVariants(...)}> 而不是水合(hydrated)的 <button> 组件。

Tailwind v4 + 共享 token(关键性修复)

  • Tailwind v4 通过 @tailwindcss/vite 在 astro.config.mjs 中配置(旧的 @astrojs/tailwind 集成已弃用)。
  • src/styles/global.css 导入了共享主题,并且添加了 Astro 内容源:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    共享的 globals.css 只会扫描 .ts/.tsx 文件,因此如果没有添加 @source,在 .astro 标记中编写的工具类永远不会被生成(它们会静默地不生效)。
  • CSS 注释陷阱: 如果 CSS 注释中包含 **/ 这样的 glob 模式(例如描述 apps/**/*),会导致注释提前闭合(因为 */),从而破坏后续的规则。请避免在注释中使用 glob 模式。

动态数据(必要时)

  • 落地页没有 React provider 和 WorkOS 认证。对于表单或动态调用,使用 Astro 服务器端点,配合 convex/browser 中的 ConvexHttpClient 进行一次性变更/查询 — 不要使用 ConvexReactClient 或 ConvexProviderWithAuth。

注意事项

  • 导入完整的 @workspace/ui/globals.css 会引入额外的主题变量/动画 — 没关系,Tailwind 会摇树优化未使用的工具类。
  • 这里没有 next-themes,因此落地页默认仅支持亮色模式,除非你添加一个简短的 .dark 切换内联脚本。
  • 不能使用 next/font — 使用 @fontsource/* 或 <link> 标签来确保字体一致。

验证方式

  • 执行 pnpm --filter landing build → 生成静态 dist/ 目录;对于没有 client:* 指令的页面,index.html 中不应包含任何 <script> 标签。
  • 仅在 .astro 文件中使用的类(例如 bg-primary)会出现在构建后的 CSS 中(说明 @source 修复起作用)。
  • 执行 pnpm --filter landing typecheck(astro check)应通过检查。

相关技能