Communitygithub.com

ASoudy/AGS

Astro を使用してコンテンツ重視のウェブサイトを構築 — デフォルトでゼロJS、アイランドアーキテクチャ、マルチフレームワークコンポーネント、Markdown/MDX 対応。

AGS とは?

このスキルは、Astro ウェブフレームワークを使用したコンテンツ豊富なウェブサイト(ブログ、ドキュメントサイト、ポートフォリオ、マーケティングサイト、eコーマス)の構築を支援します。Astro の核となる革新は**アイランドアーキテクチャ**で、デフォルトではブラウザに JavaScript を一切送信しません。インタラクティブなコンポーネントは、分離された「アイランド」として選択的にハイドレーションされます。Astro は React、Vue、Svelte、Solid などの UI フレームワークを同一プロジェクト内で同時にサポートします。このスキルは、プロジェクトのセットアップ、Astro コンポーネントの構文、ファイルベースルーティング、コンテンツコレクション、アイランドによる選択的ハイドレーション、レイアウト、SSR モードについてステップバイステップで説明します。実用的な例(RSS フィード、API エンドポイント、React アイランド)とベストプラクティスも含まれているため、開発者は効率的でパフォーマンスの高い Astro サイトをすぐに構築開始できます。

対応✓Claude Code~Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/astro

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

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

ドキュメント

Astro ウェブフレームワーク

概要

Astro は、コンテンツが豊富なウェブサイト(ブログ、ドキュメント、ポートフォリオ、マーケティングサイト、eコマース)向けに設計されたウェブフレームワークです。その中核的な革新はアイランドアーキテクチャです。デフォルトでは、Astro はブラウザに JavaScript を一切送信しません。インタラクティブなコンポーネントは、分離された「アイランド」として選択的にハイドレーションされます。Astro は React、Vue、Svelte、Solid、その他の UI フレームワークを同一プロジェクト内で同時にサポートし、コンポーネントごとに適切なツールを選択できます。

このスキルを使用するタイミング

  • ブログ、ドキュメントサイト、マーケティングページ、ポートフォリオを構築する場合
  • パフォーマンスと Core Web Vitals が最優先の場合
  • プロジェクトが Markdown または MDX ファイルでコンテンツが豊富な場合
  • SSG(静的)出力を希望し、動的なルートにはオプションで SSR を使用したい場合
  • ユーザーが .astro ファイル、Astro.props、コンテンツコレクション、client: ディレクティブについて質問した場合

仕組み

ステップ 1: プロジェクトセットアップ

npm create astro@latest my-site
cd my-site
npm install
npm run dev

必要に応じて統合機能を追加:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # React コンポーネントサポート
npx astro add mdx             # MDX サポート
npx astro add sitemap         # 自動 sitemap.xml
npx astro add vercel          # Vercel SSR アダプター

プロジェクト構造:

src/
  pages/          ← ファイルベースルーティング (.astro, .md, .mdx)
  layouts/        ← 再利用可能なページシェル
  components/     ← UI コンポーネント (.astro, .tsx, .vue など)
  content/        ← タイプセーフなコンテンツコレクション (Markdown/MDX)
  styles/         ← グローバル CSS
public/           ← 静的アセット (そのままコピー)
astro.config.mjs  ← フレームワーク設定

ステップ 2: Astro コンポーネント構文

.astro ファイルは、上部にコードフェンス(サーバー専用)を持ち、その下にテンプレートがあります:

---
// src/components/Card.astro
// このブロックはサーバー上でのみ実行されます — ブラウザでは実行されません
interface Props {
  title: string;
  href: string;
  description: string;
}

const { title, href, description } = Astro.props;
---

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

<style>
  /* このコンポーネントに自動的にスコープされます */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

ステップ 3: ファイルベースのページとルーティング

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (動的)
src/pages/blog/[...path].astro → /blog/* (キャッチオール)

getStaticPaths を使用した動的ルート:

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<h1>{post.data.title}</h1>
<Content />

ステップ 4: コンテンツコレクション

コンテンツコレクションは、Markdown および MDX ファイルへのタイプセーフなアクセスを提供します:

// src/content/config.ts
import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';

const posts = (await getCollection('blog'))
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

<ul>
  {posts.map(post => (
    <li>
      <a href={`/blog/${post.slug}`}>{post.data.title}</a>
      <time>{post.data.date.toLocaleDateString()}</time>
    </li>
  ))}
</ul>

ステップ 5: アイランド — 選択的ハイドレーション

デフォルトでは、UI フレームワークコンポーネントは JS なしで静的な HTML にレンダリングされます。client: ディレクティブを使用してハイドレーションします:

---
import Counter from '../components/Counter.tsx';  // React コンポーネント
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- 静的な HTML — JavaScript はブラウザに送信されません -->
<Counter initialCount={0} />

<!-- ページ読み込み時に即座にハイドレーション -->
<Counter initialCount={0} client:load />

<!-- コンポーネントがビューにスクロールされたときにハイドレーション -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- ブラウザがアイドル状態のときにのみハイドレーション -->
<Analytics client:idle />

<!-- 特定のメディアクエリでのみハイドレーション -->
<MobileMenu client:media="(max-width: 768px)" />

ステップ 6: レイアウト

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = 'My Astro Site' } = Astro.props;
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- ページコンテンツはここにレンダリングされます -->
    </main>
    <footer>...</footer>
  </body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="About Us">
  <h1>About Us</h1>
  <p>Welcome to our company...</p>
</BaseLayout>

ステップ 7: SSR モード(オンデマンドレンダリング)

アダプターを設定して動的ページの SSR を有効にする:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),
});

export const prerender = false を使用して個々のページを SSR にオプトインします。

例

例 1: RSS フィード付きブログ

// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'My Blog',
    description: 'Latest posts',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

例 2: API エンドポイント (SSR)

// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const { email } = await request.json();

  if (!email) {
    return new Response(JSON.stringify({ error: 'Email required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  await addToNewsletter(email);
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};

例 3: アイランドとしての React コンポーネント

// src/components/SearchBox.tsx
import { useState } from 'react';

export default function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  async function search(e: React.FormEvent) {
    e.preventDefault();
    const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
    setResults(data);
  }

  return (
    <form onSubmit={search}>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button type="submit">Search</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- 即座にハイドレーション — このアイランドはインタラクティブです -->
<SearchBox client:load />

ベストプラクティス

  • ✅ ほとんどのコンポーネントは静的な .astro ファイルとして維持する — インタラクティブにする必要があるものだけをハイドレーションする
  • ✅ すべての Markdown/MDX コンテンツにコンテンツコレクションを使用する — タイプセーフと自動検証が得られる
  • ✅ スクロールしないと表示されないコンポーネントには client:load よりも client:visible を優先して使用し、初期 JS を削減する
  • ✅ 環境変数には import.meta.env を使用する — 公開変数には PUBLIC_ プレフィックスを付ける
  • ✅ astro:transitions から <ViewTransitions /> を追加して、完全な SPA なしでスムーズなページナビゲーションを実現する
  • ❌ すべてのコンポーネントに client:load を使用しない — これでは Astro のパフォーマンス上の利点が失われる
  • ❌ クライアント向けテンプレートで使用される .astro フロントマターに機密情報を入れない
  • ❌ 静的モードの動的ルートで getStaticPaths を省略しない — ビルドが失敗する

セキュリティと安全性に関する注意事項

  • .astro ファイル内のフロントマターコードはサーバーサイドでのみ実行され、ブラウザに公開されることはありません。
  • 機密性の低い値にのみ import.meta.env.PUBLIC_* を使用します。プライベート環境変数(PUBLIC_ プレフィックスなし)はクライアントに送信されません。
  • SSR モードを使用する場合、データベースクエリや API 呼び出しの前にすべての Astro.request 入力を検証します。
  • set:html でレンダリングする前に、ユーザー提供のコンテンツをサニタイズします — 自動エスケープをバイパスします。

よくある落とし穴

  • 問題: React/Vue コンポーネントからの JavaScript がブラウザで実行されない 解決策: client: ディレクティブ(client:load、client:visible など)を追加します — これがないと、コンポーネントは静的な HTML としてのみレンダリングされます。

  • 問題: 開発中にコンテンツが更新された後、getStaticPaths のデータが古くなる 解決策: Astro の開発サーバーはコンテンツファイルを監視します — content/config.ts への変更が反映されない場合は再起動してください。

  • 問題: Astro.props の型が any でオートコンプリートが効かない 解決策: フロントマターに Props インターフェースまたは型を定義すると、Astro が自動的に推論します。

  • 問題: .astro コンポーネントからの CSS が他のコンポーネントに漏れる 解決策: .astro の <style> タグ内のスタイルは自動的にスコープされます。子要素を意図的にターゲットにする場合にのみ :global() を使用してください。

関連スキル

  • @sveltekit — リアクティブな UI を備えたフルスタックフレームワークが必要な場合(Astro のコンテンツ重視に対して)
  • @nextjs-app-router-patterns — React ファーストのフルスタックフレームワークが必要な場合
  • @tailwind-patterns — Astro サイトを Tailwind CSS でスタイリングする
  • @progressive-web-app — Astro サイトに PWA 機能を追加する

制限事項

  • このスキルは、タスクが上記の範囲に明確に一致する場合にのみ使用してください。
  • 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
  • 必要な入力、権限、安全境界、成功基準が不足している場合は、立ち止まって明確化を求めてください。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

関連スキル