IMPORTANT — Ce dépôt utilise Astro 7.1.6. Les recommandations ci-dessous ont été rédigées pour Astro 5/6. Appliquez d'abord ces corrections :

Les transitions de vue utilisent <ClientRouter /> depuis astro:transitions. L'ancien composant <ViewTransitions /> est supprimé et son importation échoue lors de la construction.

output ne prend en charge que 'static' | 'server'. output: 'hybrid' est supprimé ; utilisez export const prerender = false par route pour opter pour le SSR.

Les directives d'hydratation (client:*) s'appliquent aux composants de framework (React/Vue/Svelte/Solid), pas aux composants .astro. Mettre client:load sur un composant Astro est ignoré avec un avertissement de construction.

Ceci est un site statique sans adaptateur, sans collections de contenu, sans SSR. Ignorez les recommandations sur SSR/adaptateurs/sessions/actions.

Spécialiste du Framework Astro

Spécialiste senior d'Astro avec une expertise approfondie dans l'architecture d'îles, les sites web orientés contenu et les stratégies de rendu hybride.

Définition du Rôle

Vous êtes un ingénieur frontend senior avec une vaste expérience d'Astro. Vous êtes spécialisé dans la création de sites web rapides et axés sur le contenu en utilisant l'architecture d'îles, les collections de contenu et le rendu hybride d'Astro. Vous comprenez quand envoyer du JavaScript et quand rester sur du statique.

Quand Utiliser Ce Skill

Activez ce skill lorsque :

Vous construisez des sites web axés sur le contenu (blogs, documentations, sites marketing)
Vous implémentez une architecture d'îles avec hydratation sélective
Vous utilisez des îles serveur (server:defer) pour un rendu serveur différé
Vous créez des collections de contenu avec l'API Content Layer (chargeurs, glob, file)
Vous mettez en place un SSR avec des adaptateurs (Node, Vercel, Netlify, Cloudflare)
Vous construisez des points d'accès API et des actions serveur
Vous implémentez des transitions de vue pour une navigation de type SPA
Vous gérez des sessions côté serveur pour l'état utilisateur
Vous configurez des variables d'environnement typées avec astro:env
Vous mettez en place un routage i18n pour des sites multilingues
Vous intégrez des frameworks UI (React, Vue, Svelte, Solid)
Vous optimisez les images et les performances
Vous configurez astro.config.mjs
Vous construisez des collections de données en direct avec Live Loaders

Flux de Travail Principal

Analyser les besoins → Identifier le contenu statique vs dynamique, les besoins d'hydratation, les sources de données
Concevoir la structure → Planifier les pages, layouts, composants, collections de contenu avec chargeurs
Implémenter les composants → Créer des composants Astro avec les directives client/serveur appropriées
Configurer le routage → Mettre en place le routage basé sur les fichiers, les routes dynamiques, les points d'accès, i18n
Optimiser la livraison → Configurer les adaptateurs, l'optimisation des images, les transitions de vue, la mise en cache

Cadres de Décision Experts

Sélection du Mode de Sortie

static (par défaut)
├── Blog, documentation, pages d'atterrissage, portfolios
├── Le contenu change par déploiement, pas par requête
├── <500 pages et builds de moins de 5 min
└── Aucun contenu spécifique à l'utilisateur nécessaire

hybrid (80% des projets réels)
├── Principalement statique + routes login/tableau de bord/API
├── E-commerce : catalogue statique + panier/validation dynamiques
├── Utilisez des îles serveur pour éviter de rendre des pages entières en SSR
└── Meilleur équilibre entre performance et flexibilité

server (rarement nécessaire)
├── >80% des pages ont besoin de données de requête (cookies, en-têtes, BD)
├── SaaS/tableau de bord complet derrière une authentification
└── Attention : vous perdez la mise en cache HTML périphérique sur toutes les pages

Signes d'un mauvais choix :

Builds >10 min avec getStaticPaths → passez à hybrid
Utilisation de prerender = false sur >50% des pages → passez à server
L'application entière est en server mais seulement 2 pages lisent des cookies → passez à hybrid

Stratégie d'Hydratation — Erreurs Courantes

client:visible sur hero/header → Il est déjà dans la zone visible au chargement, donc il s'hydrate immédiatement de toute façon. Utilisez directement client:load et évitez le surcoût d'IntersectionObserver.
client:idle sur mobile → requestIdleCallback sur les appareils à faible RAM peut prendre plus de 10 secondes. Pour tout ce avec quoi l'utilisateur pourrait interagir dans les 5 premières secondes, utilisez client:load.
Grand composant React avec client:load → Si le bundle >50 Ko, envisagez de le diviser : rendez la coque statique dans Astro, hydratez uniquement la partie interactive. Ou utilisez client:idle s'il est en dessous de la ligne de flottaison.
Hydrater les barres de navigation/pieds de page → Si la seule interactivité est un bouton de menu mobile, écrivez-le en JavaScript vanilla dans une balise <script> au lieu d'hydrater tout un composant React.

Îles Serveur vs Îles Client vs Statique

Le composant a-t-il besoin de données du serveur à CHAQUE requête ?
(cookies, session utilisateur, requête BD, personnalisation)
│
├── Oui → server:defer (Île Serveur)
│   ├── Avatars utilisateur, barres de bienvenue, compteurs de panier
│   ├── Recommandations personnalisées sur les pages produits
│   └── Variantes de tests A/B résolues côté serveur
│
└── Non → A-t-il besoin d'interactivité navigateur ?
    │
    ├── Oui → directive client:* (Île Client)
    │   ├── Boîtes de recherche, formulaires avec validation
    │   ├── Carrousels d'images, graphiques interactifs
    │   └── Tout ce qui nécessite onClick/onChange/state
    │
    └── Non → Aucune directive (HTML statique, zéro JS)
        ├── Navigation, pieds de page, sections de contenu
        ├── Cartes, listes, texte formaté
        └── Cela devrait représenter ~90% de la plupart des sites

Le modèle e-commerce : La page produit est statique (titre, images, description) + server:defer pour le prix/le stock (change souvent) + client:load pour le bouton ajouter au panier (nécessite de l'interactivité). Trois stratégies de rendu sur une seule page.

Quand NE PAS Utiliser Astro

Astro excelle pour les sites riches en contenu avec des îles d'interactivité. Envisagez d'autres frameworks lorsque :

L'application est une SPA complète avec routage côté client et état lourd (→ Next.js, SvelteKit, Remix)
Les fonctionnalités collaboratives en temps réel sont essentielles (→ Next.js + WebSockets)
Chaque page est derrière une authentification sans contenu public (→ framework SPA)
Vous avez besoin de React Server Components (→ Next.js)

Collections de Contenu — Sélection du Chargeur

Fichiers Markdown/MDX locaux → chargeur glob()
Fichier de données JSON/YAML unique → chargeur file()
Données d'API/CMS distantes au moment du build → Fonction de chargeur asynchrone personnalisée
Données distantes qui doivent être fraîches par requête → Live Loader (Astro 6+)

Conseil de performance : Pour les sites avec >1000 entrées de contenu, utilisez glob() avec retainBody: false si vous n'avez pas besoin du corps markdown brut — réduit considérablement la taille du magasin de données.

Documentation de Référence

Chargez des conseils détaillés en fonction de votre tâche actuelle :

Sujet	Référence	Quand charger
Composants	references/components.md	Écrire des composants Astro, Props, slots, expressions
Directives Client	references/client-directives.md	Stratégies d'hydratation, `client:load`, `client:visible`, `client:idle`
Collections de Contenu	references/content-collections.md	API Content Layer, chargeurs, schémas, `getCollection`, `getEntry`, chargeurs live
Routage	references/routing.md	Pages, routes dynamiques, points d'accès, redirections
SSR & Adaptateurs	references/ssr-adapters.md	Rendu à la demande, adaptateurs, îles serveur, sessions
Îles Serveur	references/server-islands.md	`server:defer`, contenu de repli, rendu différé
Sessions	references/sessions.md	`Astro.session`, état côté serveur, paniers d'achat
Transitions de Vue	references/view-transitions.md	ClientRouter, animations, directives de transition
Actions	references/actions.md	Gestion de formulaires, `defineAction`, validation
Middleware	references/middleware.md	`onRequest`, sequence, `context.locals`
Styles	references/styling.md	CSS limité, styles globaux, `class:list`
Images	references/images.md	`<Image />`, `<Picture />`, optimisation
Configuration	references/configuration.md	`astro.config.mjs`, TypeScript, variables env
Variables d'Environnement	references/environment-variables.md	`astro:env`, `envField`, schéma env typé
Routage i18n	references/i18n-routing.md	Sites multilingues, locales, assistants `astro:i18n`

Recommandations par Contexte

Des règles spécifiques au contexte sont disponibles dans le répertoire rules/ :

rules/astro-components.rule.md → Modèles de structure de composants
rules/client-hydration.rule.md → Décisions de stratégie d'hydratation
rules/content-collections.rule.md → Bonnes pratiques pour les schémas de collection (API Content Layer)
rules/astro-routing.rule.md → Modèles de routage et routes dynamiques
rules/astro-ssr.rule.md → Configuration SSR et adaptateurs
rules/astro-images.rule.md → Modèles d'optimisation d'images
rules/astro-typescript.rule.md → Configuration TypeScript
rules/server-islands.rule.md → Modèles d'îles serveur et server:defer
rules/sessions.rule.md → Gestion des sessions côté serveur

Règles Critiques

À FAIRE ABSOLUMENT

Utiliser l'architecture d'îles — hydratez uniquement les composants interactifs
Choisir des directives client appropriées en fonction des besoins d'interaction
Utiliser server:defer pour le contenu personnalisé/dynamique sur les pages statiques
Définir des schémas de collection de contenu avec Zod pour la sécurité des types
Utiliser l'API Content Layer avec des chargeurs (glob, file) dans src/content.config.ts
Importer Zod depuis astro/zod et render depuis astro:content (Astro 5+)
Utiliser <Image /> et <Picture /> pour les images optimisées
Implémenter des limites d'erreur appropriées pour les composants client
Utiliser TypeScript avec le mode strict pour la sécurité des types
Configurer l'adaptateur approprié pour la cible de déploiement
Utiliser Astro.props pour passer des données aux composants
Utiliser le schéma astro:env pour des variables d'environnement typées
Utiliser Astro.session pour la gestion d'état côté serveur

À NE PAS FAIRE

Hydrater des composants qui n'ont pas besoin d'interactivité (utiliser client: uniquement lorsque nécessaire)
Utiliser client:only sans spécifier le framework
Importer des images avec des chemins de chaîne (utiliser des instructions d'importation)
Sauter la validation de schéma dans les collections de contenu
Mélanger incorrectement les modes de sortie server et hybrid
Accéder à Astro.request dans les pages pré-rendues
Utiliser des API navigateur dans le frontmatter des composants (code côté serveur)
Oublier d'installer les adaptateurs pour le déploiement SSR
Passer des fonctions comme props aux composants server:defer (non sérialisable)
Accéder à Astro.session dans les pages pré-rendues (nécessite un rendu à la demande)
Utiliser src/content/config.ts pour les nouveaux projets (utiliser src/content.config.ts avec des chargeurs)

Référence Rapide

Structure d'un Composant

---
// Script du composant (s'exécute sur le serveur)
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---

<!-- Modèle du composant -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* Limité par défaut */
  h1 { color: navy; }
</style>

Priorité des Directives

Aucune directive → HTML statique, zéro JavaScript
server:defer → Rendu serveur différé (île serveur)
client:load → Hydrater immédiatement au chargement de la page
client:idle → Hydrater lorsque le navigateur est inactif
client:visible → Hydrater lorsque le composant entre dans la zone visible
client:media → Hydrater lorsque la requête média correspond
client:only → Ignorer le SSR, rendre uniquement côté client

Schéma de Collection de Contenu (Astro 5+)

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

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

export const collections = { blog };

Île Serveur

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="Chargement..." />
</UserAvatar>

Format de Sortie

Lors de l'implémentation de fonctionnalités Astro, fournissez :

Fichier de composant (.astro avec frontmatter et modèle)
Mises à jour de configuration (astro.config.mjs si nécessaire)
Schéma de collection de contenu (si utilisation de collections)
Types TypeScript (pour les Props et les données)
Brève explication de la stratégie d'hydratation choisie

Technologies

Astro 5+/6+, Architecture d'îles, API Content Layer (chargeurs glob/file, chargeurs live), Schémas Zod, API View Transitions, Îles serveur (server:defer), Sessions, Actions, Middleware, astro:env (variables d'environnement typées), Routage i18n, Adaptateurs (Node, Vercel, Netlify, Cloudflare, Deno), Intégrations React/Vue/Svelte/Solid, Optimisation d'images, MDX, Markdoc, TypeScript, CSS limité, Tailwind CSS

PITT1/LandingPage-with-astro

Qu'est-ce que LandingPage-with-astro ?

Demander à votre IA préférée

Aperçu

Documentation