Communitygithub.com

five-angles-company/convex-starter

用於編輯 Astro 行銷網站 (apps/landing) 的技能。涵蓋零 JS 模型、Tailwind v4 修正、以及使用 Convex 處理靜態網站的動態資料。

convex-starter 是什麼?

此技能專注於管理 `apps/landing` 目錄下的 Astro 靜態行銷網站。它強制執行零客戶端 JavaScript 的架構,僅在必要時透過 `client:*` 指令選擇性地掛載 React 互動元件(島嶼)。技能文件中明確指出了 Tailwind v4 的關鍵修正:由於共用主題套件 `@workspace/ui/globals.css` 預設只掃描 `.ts/.tsx` 檔案,因此需要在 Astro 專案中額外加入 `@source` 指令,才能正確產生在 `.astro` 模板中使用的工具類別樣式。若需要動態資料(如表單提交),技能建議使用 `ConvexHttpClient` 建立伺服器端端點,而非使用需 React Context 支援的 `ConvexReactClient`。此技能也記錄了 CSS 註解中因包含 `**/` 全域模式而導致解析錯誤的陷阱,以及與 Next.js 的差異(如無 `next-themes` 與 `next/font` 支援)。主要驗證方式是透過 `pnpm --filter landing build` 確認輸出為不含腳本標籤的靜態 HTML。

相容平台~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 島嶼內 — React 的 Context 在獨立的 Astro 島嶼之間是無法共享的。
  • 對於樣式為按鈕的連結,請優先使用 <a class={buttonVariants(...)}> 而非水合的按鈕元件。

Tailwind v4 + 共享權杖(關鍵修正)

  • Tailwind v4 是透過 astro.config.mjs 中的 @tailwindcss/vite 設定的(舊的 @astrojs/tailwind 整合已棄用)。
  • src/styles/global.css 匯入了共享主題,並新增了一個 Astro 內容來源:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    共享的 globals.css 僅掃描 .ts/.tsx,因此若沒有加上 @source,在 .astro 標記中撰寫的工具類別將永遠不會被產生(它們會默默地不生效)。
  • CSS 註解陷阱: 一個包含 **/ 全域模式的 CSS 註解(例如描述 apps/**/*)會提前關閉註解(因為 */),導致後續的規則損毀。請將全域模式排除在註解之外。

動態資料(必要時)

  • 登陸頁面沒有 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)通過。

相關技能