diegosouzapw/awesome-omni-skills

Framework Web Astro

Aperçu

Cette copie d'entrée publique empaquète plugins/antigravity-awesome-skills/skills/astro depuis https://github.com/sickn33/antigravity-awesome-skills dans le format éditorial natif d'Omni Skills sans dissimuler son origine.

Utilisez-la lorsque l'opérateur doit préserver le workflow amont, les fichiers de support et le contexte du répertoire intacts, tandis que le validateur public et l'améliorateur privé poursuivent leur flux aval normal.

Cette entrée conserve les fichiers amont copiés intacts et utilise le bloc external_source dans metadata.json ainsi que ORIGIN.md comme ancrage de provenance pour la révision.

Framework Web Astro

Les sections de source importée qui n'ont pas été proprement mappées aux en-têtes publics sont tout de même conservées ci-dessous ou dans les fichiers de support. Sections importées notables : Comment ça fonctionne, Notes de sécurité et de sûreté, Pièges courants, Limitations.

Quand utiliser cette compétence

Utilisez cette section comme filtre de déclenchement. Elle doit rendre explicite la limite d'activation avant que l'opérateur ne charge des fichiers, n'exécute des commandes ou n'ouvre une demande de tirage (pull request).

• Utilisez-la lors de la construction d'un blog, d'un site de documentation, d'une page marketing ou d'un portfolio
• Utilisez-la lorsque la performance et les Core Web Vitals sont la priorité absolue
• Utilisez-la lorsque le projet est riche en contenu avec des fichiers Markdown ou MDX
• Utilisez-la lorsque vous souhaitez une sortie SSG (statique) avec un SSR optionnel pour les routes dynamiques
• Utilisez-la lorsque l'utilisateur pose des questions sur les fichiers .astro, Astro.props, les collections de contenu ou les directives client:
• Utilisez-la lorsque la demande correspond clairement à l'intention de la source importée : Construire des sites web centrés sur le contenu avec Astro — zéro JavaScript par défaut, architecture en îlots, composants multi-frameworks et support Markdown/MDX.

Tableau de fonctionnement

Situation	Commencer ici	Pourquoi c'est important
Première utilisation	metadata.json	Confirme le répertoire, la branche, le commit et le chemin importé via le bloc external_source avant de toucher au workflow copié
Révision de la provenance	ORIGIN.md	Fournit aux réviseurs une piste d'audit en langage clair pour la source importée
Exécution du workflow	SKILL.md	Commence par le plus petit fichier copié qui modifie matériellement l'exécution
Contexte de support	SKILL.md	Ajoute le fichier source copié le plus pertinent suivant sans charger tout le paquet
Décision de transmission	## Compétences connexes	Aide l'opérateur à passer à une compétence native plus forte lorsque la tâche dévie

Workflow

Ce workflow est intentionnellement à la fois éditorial et opérationnel. Il maintient la source importée utile à l'opérateur tout en satisfaisant les normes d'entrée publique qui alimentent le flux d'amélioration aval.

1. Confirmer l'objectif de l'utilisateur, la portée du workflow importé, et si cette compétence est toujours le bon routeur pour la tâche.
2. Lire les fichiers d'aperçu et de provenance avant de charger tout fichier de support amont copié.
3. Charger uniquement les références, exemples, invites ou scripts qui modifient matériellement le résultat pour la demande actuelle.
4. Exécuter le workflow amont tout en gardant la provenance et les limites de la source explicites dans les notes de travail.
5. Valider le résultat par rapport aux attentes amont et aux preuves que vous pouvez pointer dans les fichiers copiés.
6. Escalader ou transmettre à une compétence connexe lorsque le travail sort du centre de gravité de ce workflow importé.
7. Avant la fusion ou la clôture, enregistrer ce qui a été utilisé, ce qui a changé et ce que le réviseur doit encore vérifier.

Notes de workflow importées

Importé : Aperçu

Astro est un framework web conçu pour les sites riches en contenu — blogs, documentation, portfolios, sites marketing et e-commerce. Son innovation centrale est l'architecture en îlots : par défaut, Astro n'envoie aucun JavaScript au navigateur. Les composants interactifs sont hydratés sélectivement en tant qu'« îlots » isolés. Astro prend en charge React, Vue, Svelte, Solid et d'autres frameworks UI simultanément dans le même projet, vous permettant de choisir l'outil approprié par composant.

Importé : Comment ça fonctionne

Étape 1 : Configuration du projet

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

Ajoutez des intégrations selon vos besoins :

npx astro add tailwind        # Tailwind CSS
npx astro add react           # Support des composants React
npx astro add mdx             # Support MDX
npx astro add sitemap         # Auto sitemap.xml
npx astro add vercel          # Adaptateur SSR Vercel

Structure du projet :

src/
  pages/          ← Routage basé sur les fichiers (.astro, .md, .mdx)
  layouts/        ← Coques de page réutilisables
  components/     ← Composants UI (.astro, .tsx, .vue, etc.)
  content/        ← Collections de contenu typées (Markdown/MDX)
  styles/         ← CSS global
public/           ← Actifs statiques (copiés tels quels)
astro.config.mjs  ← Configuration du framework

Étape 2 : Syntaxe des composants Astro

Les fichiers .astro ont une barrière de code en haut (côté serveur uniquement) et un modèle en dessous :

---
// src/components/Card.astro
// Ce bloc s'exécute UNIQUEMENT sur le serveur — jamais dans le navigateur
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>
  /* Portée automatiquement à ce composant */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Étape 3 : Pages et routage basés sur les fichiers

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dynamique)
src/pages/blog/[...path].astro → /blog/* (tout attraper)

Route dynamique avec 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 />

Étape 4 : Collections de contenu

Les collections de contenu vous offrent un accès typé aux fichiers Markdown et 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>

Étape 5 : Îlots — Hydratation sélective

Par défaut, les composants des frameworks UI sont rendus en HTML statique sans JS. Utilisez les directives client: pour hydrater :

---
import Counter from '../components/Counter.tsx';  // Composant React
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- HTML statique — aucun JavaScript envoyé au navigateur -->
<Counter initialCount={0} />

<!-- Hydrater immédiatement au chargement de la page -->
<Counter initialCount={0} client:load />

<!-- Hydrater lorsque le composant défile dans la vue -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hydrater uniquement lorsque le navigateur est inactif -->
<Analytics client:idle />

<!-- Hydrater uniquement sur une requête média spécifique -->
<MobileMenu client:media="(max-width: 768px)" />

Étape 6 : Layouts

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

<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- le contenu de la page s'affiche ici -->
    </main>
    <footer>...</footer>
  </body>
</html>

---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="À propos">
  <h1>À propos</h1>
  <p>Bienvenue dans notre entreprise...</p>
</BaseLayout>

Étape 7 : Mode SSR (Rendu à la demande)

Activez le SSR pour les pages dynamiques en définissant un adaptateur :

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

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

Optez pour des pages individuelles en SSR avec export const prerender = false.

Exemples

Exemple 1 : Demander directement le workflow amont

Utilisez @astro-v2 pour gérer <tâche>. Commencez par le workflow amont copié, chargez uniquement les fichiers qui changent le résultat, et gardez la provenance visible dans la réponse.

Explication : C'est le point de départ le plus sûr lorsque l'opérateur a besoin du workflow importé, mais pas de l'intégralité du répertoire.

Exemple 2 : Demander une révision basée sur la provenance

Révisez @astro-v2 par rapport à metadata.json et ORIGIN.md, puis expliquez quels fichiers amont copiés vous chargeriez en premier et pourquoi.

Explication : Utilisez ceci avant une révision ou un dépannage lorsque vous avez besoin d'une explication précise et vérifiable de l'origine et de la sélection des fichiers.

Exemple 3 : Réduire les fichiers de support copiés avant exécution

Utilisez @astro-v2 pour <tâche>. Chargez uniquement les références, exemples ou scripts copiés qui changent le résultat, et nommez les fichiers explicitement avant de procéder.

Explication : Cela maintient la compétence alignée sur une divulgation progressive au lieu de charger tout le paquet copié par défaut.

Exemple 4 : Construire un dossier de révision

Révisez @astro-v2 en utilisant les fichiers amont copiés plus la provenance, puis résumez les lacunes avant la fusion.

Explication : Ceci est utile lorsque la PR (demande de tirage) attend une révision humaine et que vous souhaitez un dossier d'audit reproductible.

Notes d'utilisation importées

Importé : Exemples

Exemple 1 : Blog avec flux 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: 'Mon Blog',
    description: 'Derniers articles',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Exemple 2 : Point de terminaison 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 requis' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

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

Exemple 3 : Composant React en tant qu'îlot

// 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">Rechercher</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}

---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Hydraté immédiatement — cet îlot est interactif -->
<SearchBox client:load />

Meilleures pratiques

Traitez la compétence publique générée comme une couche d'emballage révisable autour du répertoire amont. L'objectif est de garder la provenance explicite et de charger uniquement le matériel source copié qui améliore matériellement l'exécution.

• ✅ Gardez la plupart des composants comme des fichiers .astro statiques — hydratez uniquement ce qui doit être interactif
• ✅ Utilisez les collections de contenu pour tout le contenu Markdown/MDX — vous obtenez la sécurité de type et l'auto-validation
• ✅ Préférez client:visible à client:load pour les composants situés sous la ligne de flottaison afin de réduire le JS initial
• ✅ Utilisez import.meta.env pour les variables d'environnement — préfixez les variables publiques avec PUBLIC_
• ✅ Ajoutez <ViewTransitions /> depuis astro:transitions pour une navigation fluide entre les pages sans un SPA complet
• ❌ N'utilisez pas client:load sur chaque composant — cela annule l'avantage de performance d'Astro
• ❌ Ne mettez pas de secrets dans le frontmatter .astro qui sont utilisés dans les modèles côté client

Notes de fonctionnement importées

Importé : Meilleures pratiques

• ✅ Gardez la plupart des composants comme des fichiers .astro statiques — hydratez uniquement ce qui doit être interactif
• ✅ Utilisez les collections de contenu pour tout le contenu Markdown/MDX — vous obtenez la sécurité de type et l'auto-validation
• ✅ Préférez client:visible à client:load pour les composants situés sous la ligne de flottaison afin de réduire le JS initial
• ✅ Utilisez import.meta.env pour les variables d'environnement — préfixez les variables publiques avec PUBLIC_
• ✅ Ajoutez <ViewTransitions /> depuis astro:transitions pour une navigation fluide entre les pages sans un SPA complet
• ❌ N'utilisez pas client:load sur chaque composant — cela annule l'avantage de performance d'Astro
• ❌ Ne mettez pas de secrets dans le frontmatter .astro qui sont utilisés dans les modèles côté client
• ❌ N'oubliez pas getStaticPaths pour les routes dynamiques en mode statique — les builds échoueront

Dépannage

Problème : L'opérateur a sauté le contexte importé et a répondu de manière trop générique

Symptômes : Le résultat ignore le workflow amont dans plugins/antigravity-awesome-skills/skills/astro, ne mentionne pas la provenance, ou n'utilise aucun fichier source copié. Solution : Rouvrez metadata.json, ORIGIN.md et les fichiers amont copiés les plus pertinents. Vérifiez d'abord le bloc external_source, puis reformulez la provenance avant de continuer.

Problème : Le workflow importé semble incomplet lors de la révision

…

[tronqué pour la traduction]