farulwananda/skills

FW Writing Astro

スコープと最初の決定

このスキルは、Astro固有のコンポーネント、ルーティング、コンテンツ、レンダリング、インテグレーションに使用します。Reactの内部構造、バックエンドアーキテクチャ、デプロイプロバイダーを指定するためには使用せず、必要な場合にのみ関連するフレームワーク/ランタイムのスキルを組み合わせてください。

編集前に、package.json、ロックファイル、Astroとアダプターのバージョン、astro.config.*、tsconfig、既存のルート/レイアウト/コンテンツ設定、リポジトリのスクリプトを検査してください。インストールされているバージョンのドキュメントと既存の規約に従ってください。許可なくインテグレーションのインストール、依存関係のアップグレード、デプロイ、有料サービスの呼び出しを行わないでください。

• 事前にビルドできるコンテンツには、プリレンダリングされたHTMLを優先します。フロントマターはプリレンダリングされたルートではビルド時に、オンデマンドルートではサーバー上で実行されます。ブラウザコードではありません。
• 認証コンテンツや新しいデータなど、実際のリクエスト時要件にはSSRを使用します。互換性のあるアダプターが必要です。現在のモデルをサポートするバージョンでは、デフォルトの静的出力で export const prerender = false を使用して個々のルートをSSRにオプトインできます。output: 'server' はSSRをデフォルトにし、prerender = true の例外を許可します。古いバージョンではハイブリッド設定が異なります。移行前に検査してください。
• 完全に静的なサイトは通常アダプターを必要としません。AstroをCloudflareと同一視したり、静的コンテンツにSSRを強制したりしないでください。
• アクセシビリティ、エスケープ、信頼境界を維持してください。信頼できないHTMLを set:html で補間しないでください。信頼できる形式のレンダリングは、実際の入力境界でサニタイズしてください。

ネイティブコンポーネントと有効なプロパティ

レイアウトと静的なコンテンツには .astro コンポーネントを使用します。コンポーネントがプロパティを受け取る場合は Props を宣言します。プロパティのないページに儀式的なインターフェースは必要ありません。実際の要素の属性を使用し、意図的に属性を転送し、互換性のない属性セットを持つポリモーフィックタグを避けてください。リンクカードは、href をarticleに送る代わりに、article内のリンクを使用できます。ラッピングアンカー内にインタラクティブなコントロールをネストしないでください。

ASTRO-CARD — 完全な src/components/Card.astro。CSSライブラリは不要です：

---
import type { HTMLAttributes } from 'astro/types';

interface Props extends Omit<HTMLAttributes<'article'>, 'title'> {
  title: string;
  description?: string;
  href?: string;
}

const { title, description, href, class: className, ...rest } = Astro.props;
---

<article {...rest} class:list={['card', className]}>
  <h2>{href ? <a href={href}>{title}</a> : title}</h2>
  {description && <p>{description}</p>}
  <slot />
</article>

明示的なコンテンツ領域には名前付きスロットを、条件付きクラスには class:list を使用します。信頼できないリンク先は個別に検証してください。文字列型はURLバリデーションではありません。

フレームワークアイランド前の小さなブラウザ動作

まずセマンティックHTML（details、ネイティブフォーム）を使用し、ブラウザの動作が必要な場合にのみ、小さな処理済み <script> を使用します。メニューの切り替えのためにReact/Vue/Svelteを追加しないでください。Astroスクリプトはバンドル/重複排除されます。すべてのコンポーネントインスタンスを選択するか、スコープ付きカスタム要素を使用します。クライアントサイドナビゲーションでは、インストールされているルーターのライフサイクルに従い、重複したリスナーを避けてください。フロントマターの値はブラウザスクリプトで自動的に利用できません。明示的なDOM属性またはプロパティを通じて、秘密情報でないデータのみを渡してください。

ASTRO-BUTTON — 完全な src/components/Counter.astro。通常の全ページナビゲーション用：

<button type="button" data-counter aria-label="カウントを増やす">0</button>
<script>
  document.querySelectorAll<HTMLButtonElement>('button[data-counter]').forEach((button) => {
    let count = 0;
    button.addEventListener('click', () => {
      button.textContent = String(++count);
    });
  });
</script>

既存のフレームワークコンポーネントまたはかなりのインタラクティブ状態が必要で、既にインストールされているインテグレーションがある場合に、フレームワークアイランドを使用します。即時の動作が必要な場合は client:load、重要でない動作には client:idle、画面外のコンテンツには client:visible、実際のメディア依存要件には client:media を選択してください。client:* ディレクティブのないコンポーネントは、フレームワークのハイドレーションなしでHTMLをレンダリングします。client:only はサーバーレンダリングをスキップするため、意図的なローディング/フォールバック体験が必要であり、包括的な回避策として使用しないでください。

コンテンツコレクションはインストールバージョンに従う

繰り返しの構造化コンテンツにはコレクションを使用し、隔離されたすべてのページには使用しません。編集前に既存の設定とエントリ識別子を検査してください：

• Astro 5 では、通常 src/content.config.ts にあるContent Layerローダーモデルが導入されました。レガシープロジェクトは、ローダーではなく src/content/config.ts と type: 'content' を使用する場合があります。これらのファイルの場所/APIは互換性がありません。
• インストールされているZodのエクスポートを確認してください。以下の例はAstro 5の astro:content からの z エクスポートを対象としています。現在のドキュメントでは astro/zod を使用しています。そのモジュールがないバージョンでは、機械的にインポートを置き換えないでください。
• ローダーエントリは id を使用します。レガシーの slug や entry.render() APIを想定しないでください。Content Layerレンダリングには、サポートされている render(entry) ヘルパーを使用します。MDXファイルが含まれている場合、MDXにはそのインテグレーションが必要です。

ASTRO-COLLECTION-V5 — ローカルMarkdownエントリを使用したAstro 5用の完全な src/content.config.ts：

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

ASTRO-COLLECTION-LIST — そのコレクションと少なくとも1つのスキーマ検証済みMarkdownエントリとペアになった完全なページ src/pages/blog/index.astro：

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog', ({ data }) => !import.meta.env.PROD || !data.draft);
posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<h1>ブログ</h1>
<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

このリストは意図的に詳細ページURLを発明しません。リンクを追加する場合は、一致する動的ルートとプリレンダリングページ用の getStaticPaths() を実装してください。詳細ルートでも下書きをチェックしてください。リストのみをフィルタリングすることはアクセス制御ではありません。リクエスト時のプライベートコンテンツは、ビルド出力やパブリックキャッシュを通じて漏洩してはいけません。

ロケール、正規URL、404の一貫性

ルートを変更する前にURLポリシーを選択してください：設定された本番 site、デプロイ base、末尾スラッシュ/ビルド形式、ロケールプレフィックス、ルートの動作、フォールバック動作は、実際のファイルとホストのリダイレクトと一致している必要があります。

• フォルダベースのルートを使用します。prefixDefaultLocale: false の場合、デフォルト言語のページはルートに配置されます。他のロケールはフォルダを持ちます。true の場合、すべての言語がロケールフォルダを持ち、ルートインデックスは依然として意図的な処理が必要です。
• バージョンでサポートされている astro:i18n ヘルパーを有用な場合に使用します。設定はコンテンツを翻訳したり、欠落しているページを作成したりしません。既存の翻訳のみにリンクしてください。言語を切り替える際に意味のある同等のパスを維持してください。
• 正規URLは、本番オリジンと選択された正規パス名を使用する必要があり、Astro.url.href からの任意のリクエストホスト/クエリパラメータは使用しません。デプロイ用に site を設定します。base と末尾スラッシュの正規化を考慮してください。ドキュメントの lang を設定し、相互リンクがある実際の同等物に対してのみ hreflang の代替を出力します。すべてのロケールを英語に正規化しないでください。
• カスタムエラーページが必要な場合に src/pages/404.astro を実装します。SSRパスでは、成功したエラーボディではなく、実際の404ステータスを返します。静的ホスティングでは、生成された404ファイルがステータス404で提供されることを確認します。マルチページサイトにSPAフォールバックを使用したり、欠落しているすべてのロケールパスをホームページにリダイレクトしたりしないでください。エラーページのインデックス作成を避け、欠落しているすべてのURLに自己正規URLを与えないでください。

ASTRO-CANONICAL-FRAGMENT — 部分的なレイアウト例。スタンドアロンページではありません。site が設定されており、現在のパス名がすでにリポジトリのベース/ロケール/スラッシュポリシーに従っていることを前提とします。

---
if (!Astro.site) throw new Error('本番サイトのURLを設定してください');
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<link rel="canonical" href={canonical} />

アセットとデプロイの境界

処理が有益な画像には、src/assets/ と astro:assets の Image を優先します。変更されていないURL、robots.txt、アイコンを必要とするアセットは public/ に保持します。通常の <img> は、意図的なパススルー/リモートケースに有効です。意味のある alt（装飾画像の場合は空）と、内在的な寸法または同等のレイアウト制約を指定します。レスポンシブ画像APIをインストールバージョンに一致させ、すべての画像を熱心に読み込むことを避け、実際にファーストビューにある重要な画像のみを優先します。SSR画像サービスとそのランタイム/コスト要件を有効にする前に確認してください。

既存のホストのヘッダー/リダイレクトメカニズムは、必要な場合にのみ使用します。_headers と _redirects はプロバイダー固有であり、普遍的なAstro要件ではありません。アダプターSSRの場合は、手書きの汎用静的/SPA設定ではなく、そのアダプターバージョンの生成された出力とランタイムバインディング規則に従ってください。

検証と報告

許可された場合、リポジトリの既存のチェック/ビルド/テストスクリプトを使用します。プロップの型付け、出力されたルート、コレクションの検証、下書き詳細ページの公開、ロケール切り替えリンク、正規URLのオリジン/クエリ削除、ベース/スラッシュの動作、不明なルートのステータス、キーボードの動作、ブラウザコンソールエラーを確認してください。静的なビルドが成功しても、SSRランタイムの互換性や本番リダイレクトを証明しません。実際に実行されたコマンド、バージョンの仮定、欠落しているインテグレーション/コンテンツフィクスチャ、未検証のホスティング動作を報告してください。暗黙の検証ステップとしてインストール、デプロイ、またはリモートサービスのトリガーを行わないでください。

ソースと出典

これは著者の統合であり、サードパーティのスキルを大量にコピーしたものではありません。タスクとインストールバージョンに関連するドキュメントのみを読んでください：

• 公式Astro: コンポーネントとプロパティ、ブラウザスクリプト、オンデマンドレンダリング。
• 公式Astro: コンテンツコレクション、Astro 5 移行、i18n ルーティング、Cloudflare アダプター。
• astrolicious/agent-skills はコミュニティリファレンスであり、公式のAstroドキュメントや互換性の保証ではありません。選択的に参照してください。公式のバージョン一致APIドキュメントが優先されます。