Framework Web Astro
Règle de Lecture Sélective
Commencez par :
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
Chargez ensuite uniquement les documents hérités, scripts, ressources ou exemples qui correspondent à la tâche réelle de l'utilisateur.
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 principale 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 d'interface utilisateur simultanément dans le même projet, vous permettant de choisir l'outil approprié pour chaque composant.
Quand Utiliser Cette Compétence
- À utiliser lors de la construction d'un blog, d'un site de documentation, d'une page marketing ou d'un portfolio
- À utiliser lorsque la performance et les Core Web Vitals sont la priorité absolue
- À utiliser lorsque le projet est lourd en contenu avec des fichiers Markdown ou MDX
- À utiliser lorsque vous souhaitez une sortie SSG (statique) avec un SSR optionnel pour les routes dynamiques
- À utiliser lorsque l'utilisateur pose des questions sur les fichiers
.astro,Astro.props, les collections de contenu ou les directivesclient:
Comment ça Fonctionne
Étape 1 : Configuration du Projet
npm create astro@latest mon-site
cd mon-site
npm install
npm run dev
Ajoutez les intégrations selon vos besoins :
npx astro add tailwind # Tailwind CSS
npx astro add react # Prise en charge des composants React
npx astro add mdx # Prise en charge MDX
npx astro add sitemap # sitemap.xml automatique
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 d'interface utilisateur (.astro, .tsx, .vue, etc.)
content/ ← Collections de contenu typées (Markdown/MDX)
styles/ ← CSS global
public/ ← Ressources statiques (copiées telles quelles)
astro.config.mjs ← Configuration du framework
Étape 2 : Syntaxe des Composants Astro
Les fichiers .astro ont une zone 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>
/* Limité 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/* (attrape-tout)
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 donnent 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 du framework d'interface utilisateur sont rendus en HTML statique sans JavaScript. 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} />
<!-- Hydrate immédiatement au chargement de la page -->
<Counter initialCount={0} client:load />
<!-- Hydrate lorsque le composant défile dans la vue -->
<VideoPlayer src="/demo.mp4" client:visible />
<!-- Hydrate uniquement lorsque le navigateur est inactif -->
<Analytics client:idle />
<!-- Hydrate 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 : 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
- ✅ Conservez la plupart des composants sous forme de fichiers
.astrostatiques — n'hydratez que ce qui doit être interactif - ✅ Utilisez les collections de contenu pour tout le contenu Markdown/MDX — vous obtenez une sécurité de type et une validation automatique
- ✅ Préférez
client:visibleàclient:loadpour les composants en dessous de la ligne de flottaison afin de réduire le JavaScript initial - ✅ Utilisez
import.meta.envpour les variables d'environnement — préfixez les variables publiques avecPUBLIC_ - ✅ Ajoutez
<ViewTransitions />depuisastro:transitionspour une navigation fluide entre les pages sans une SPA complète - ❌ N'utilisez pas
client:loadsur chaque composant — cela annule l'avantage de performance d'Astro - ❌ Ne mettez pas de secrets dans le frontmatter
.astroqui sont utilisés dans les modèles côté client - ❌ N'omettez pas
getStaticPathspour les routes dynamiques en mode statique — les builds échoueront
Notes de Sécurité
- Le code du frontmatter dans les fichiers
.astros'exécute uniquement côté serveur et n'est jamais exposé au navigateur. - Utilisez
import.meta.env.PUBLIC_*uniquement pour les valeurs non sensibles. Les variables d'environnement privées (sans préfixePUBLIC_) ne sont jamais envoyées au client. - Lorsque vous utilisez le mode SSR, validez toutes les entrées de
Astro.requestavant les requêtes de base de données ou les appels API. - Nettoyez tout contenu fourni par l'utilisateur avant de le rendre avec
set:html— cela contourne l'auto-échappement.
Pièges Courants
-
Problème : Le JavaScript d'un composant React/Vue ne s'exécute pas dans le navigateur Solution : Ajoutez une directive
client:(client:load,client:visible, etc.) — sans elle, les composants sont rendus uniquement en HTML statique. -
Problème : Les données de
getStaticPathssont obsolètes après les mises à jour de contenu pendant le développement Solution : Le serveur de développement d'Astro surveille les fichiers de contenu — redémarrez si les modifications apportées àcontent/config.tsne sont pas reflétées. -
Problème : Le type
Astro.propsestany— pas d'autocomplétion Solution : Définissez une interface ou un typePropsdans le frontmatter et Astro l'inférera automatiquement. -
Problème : Le CSS d'un composant
.astrose répercute sur d'autres composants Solution : Les styles dans les balises<style>.astrosont automatiquement limités. Utilisez:global()uniquement lorsque vous ciblez intentionnellement les enfants.
Compétences Connexes
@sveltekit— Lorsque vous avez besoin d'un framework complet avec une interface utilisateur réactive (par opposition à l'orientation contenu d'Astro)@nextjs-app-router-patterns— Lorsque vous avez besoin d'un framework complet axé sur React@tailwind-patterns— Styliser les sites Astro avec Tailwind CSS@progressive-web-app— Ajouter des capacités PWA à un site Astro
Limitations
- Utilisez cette compétence uniquement lorsque la tâche correspond clairement au champ décrit ci-dessus.
- Ne considérez pas la sortie comme un substitut à une validation, un test ou une révision experte spécifique à l'environnement.
- Arrêtez-vous et demandez des clarifications si les entrées requises, les autorisations, les limites de sécurité ou les critères de succès sont manquants.