Communitygithub.com

five-angles-company/convex-starter

Astro マーケティングサイト (apps/landing) の編集、セクション/コンポーネント追加、shadcn/@workspace/ui の利用、Tailwind v4 スタイリング、ランディングページへの動的データ追加時に使用します。ゼロJSモデル、.astro ファイル向け Tailwind @source 修正、Convex 静的サイトパターンをまとめています。

convex-starter とは?

このスキルは、開発者が `apps/landing` ディレクトリにある Astro ベースの静的マーケティングサイトを効率的に編集および保守するためのルールとパターンを提供します。主に shadcn/ui コンポーネントと Tailwind CSS v4 を使用してブランドに一貫性を持たせながら、デフォルトでクライアント側 JavaScript をほぼゼロにする「ゼロJSモデル」を実現します。特に、Tailwind v4 の `@source` ディレクティブを使用して `.astro` ファイル内のユーティリティクラスが確実に生成されるようにする修正方法や、CSS コメント内でのグロブパターン使用によるバグの回避策を詳述しています。また、Convex を使用してフォーム送信などの動的データを扱う場合は、`ConvexHttpClient` を用いたサーバーエンドポイントを推奨し、React プロバイダーを使わないシンプルな構成を保ちます。対応プラットフォームは Astro であり、Next.js アプリやモバイル環境とは異なるランタイムであることを明示しています。このスキルに従うことで、開発者はスタイルが適用されない、予期せぬ JS が出力されるといった一般的な問題を回避し、保守性の高いランディングページを構築できます。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ランディング (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 コンテキストは個別の Astro アイランド間で共有されません。
  • ボタンとしてスタイルされたリンクには、ハイドレートされたボタンではなく <a class={buttonVariants(...)}> を推奨します。

Tailwind v4 + 共有トークン (重要な修正)

  • 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 コメント (例: apps/**/* の説明) は、コメントを早期に閉じてしまい (*/)、次のルールを壊します。コメント内にグロブを入れないでください。

動的データ (必要な場合)

  • ランディングには React プロバイダーも WorkOS 認証もありません。フォームや動的な呼び出しが必要な場合は、convex/browser の ConvexHttpClient を使用した Astro サーバーエンドポイントで一回限りのミューテーション/クエリを実行してください (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) がパスすること。

関連スキル