Guide complet SSR Astro : 3 étapes pour activer le rendu côté serveur

Votre blog Astro tourne à fond, Lighthouse à 95+, et le patron demande soudain une connexion utilisateur. Panique : comment gérer l’authentification sur un site statique ? La doc officielle déverse SSR, SSG, Hybrid, adapter — de quoi perdre le fil.

Ma première rencontre avec le SSR Astro, c’était pareil. Astro mise sur la vitesse : ajouter du rendu serveur, est-ce que tout ralentit ? Vercel, Netlify, Node.js — lequel choisir ? Et dans la config, output, prerender, ça veut dire quoi exactement ?

En réalité, configurer le SSR Astro est moins intimidant qu’il n’y paraît. Cet article explique clairement : quand le SSR est indispensable (plutôt que de rester en SSG), comment configurer rapidement les adaptateurs, et comment combiner SSR et SSG dans un même projet (mode hybride). À la fin, vous saurez juger si votre projet en a besoin — et vous pourrez être opérationnel en une trentaine de minutes.

Chapitre 1 : Concepts SSR et choix technique

Quand préférer le SSR au SSG ?

Le critère le plus simple : le contenu est-il figé au build, ou peut-il changer à chaque visite ?

Le SSG (Static Site Generation), c’est le menu préparé le matin : les plats sont prêts, le client est servi tout de suite — ultra rapide. Articles de blog, pages produit, À propos : contenu stable, le SSG est idéal.

Le SSR (Server-Side Rendering), c’est la cuisine à la commande : le plat est préparé selon la demande du client. « Bon retour, Zhang San » après connexion, cours boursiers en direct, quantité du panier — chaque visiteur voit autre chose, il faut du SSR.

Votre projet en a-t-il besoin ? Voici cinq scénarios : si l’un vous concerne, envisagez le SSR.

1. Authentification et contenu personnalisé

L’exemple classique : la connexion. Au build, vous ne savez pas qui se connectera ni quel nom afficher. Sur une plateforme d’apprentissage, j’avais « Reprendre : leçon 5 » sur l’accueil — impossible en SSG pur ; il faut du SSR selon la progression de l’utilisateur.

2. Données en temps réel

Météo, bourse, scores sportifs. Les données changent chaque minute ; rebuilder le site en continu n’a pas de sens. Avec le SSR, chaque visite récupère la version à jour.

3. Requêtes base de données

Recherche produits e-commerce : chaque mot-clé donne des résultats différents. Impossible de pré-générer toutes les combinaisons. Le SSR interroge la base au moment de la recherche.

4. Routes API

Formulaires, uploads, appels API tiers — logique backend requise. En mode SSR, Astro permet des routes API (src/pages/api/xxx.js) sans serveur backend séparé.

5. Tests A/B et recommandations

Contenu selon géolocalisation, heure, historique. Sur une grande marketplace, la page d’accueil diffère par utilisateur — personnalisation = SSR.

Question fréquente : « Et la page détail d’un article de blog en SSR ? » Possible, mais inutile. Le contenu est fixe ; le SSG génère du HTML statique, CDN plus rapide, coût serveur plus bas. Le SSR n’est pas une fin en soi.

Mode hybride : les deux approches

Le mode hybride d’Astro 2.0 permet SSG et SSR dans un même projet. Exemple e-commerce :

• Accueil, À propos, aide → SSG (chargement rapide)
• Connexion, espace utilisateur, panier → SSR (dynamique)
• Fiche produit → SSG (contenu fixe)
• Résultats de recherche → SSR (requête temps réel)

Les pages statiques gardent leur vitesse ; les fonctions dynamiques fonctionnent. Un ami gère son blog ainsi : liste et articles en SSG, zone commentaires en SSR — Lighthouse toujours autour de 95+.

Chapitre 2 : Démarrage rapide — 3 étapes pour activer le SSR

Configurer le SSR Astro from scratch (adaptateur Node.js)

Une fois le besoin SSR confirmé, passons à la configuration. Je commence par l’adaptateur Node.js — le plus polyvalent, adapté à un serveur ou VPS auto-hébergé.

Étape 1 : installer l’adaptateur en une commande

Astro fournit une commande de configuration automatique, à lancer à la racine du projet :

npx astro add node

Cette commande fait trois choses :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

1. Installe le paquet @astrojs/node
2. Modifie astro.config.mjs
3. Met à jour les dépendances dans package.json

À la fin, le terminal affiche des coches vertes : configuration OK. Installation manuelle possible si vous devez figer une version :

npm install @astrojs/node

Puis modification manuelle du fichier de config (étape suivante).

Étape 2 : modifier la configuration

Ouvrez astro.config.mjs à la racine. Après la commande automatique, vous devriez voir :

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

export default defineConfig({
  output: 'server', // Active le mode SSR
  adapter: node({
    mode: 'standalone' // Mode serveur autonome
  }),
});

Deux options importantes :

output :

• 'static' (défaut) : toutes les pages en SSG, HTML statique pur
• 'server' : toutes les pages en SSR, génération à chaque requête
• 'hybrid' : SSG par défaut, SSR page par page (recommandé)

mode :

• 'standalone' : Astro lance un serveur Node.js dédié, idéal pour déploiement direct
• 'middleware' : génère un middleware intégrable à Express, Koa, etc.

J’utilise en général standalone : le serveur intégré d’Astro suffit. Si vous avez déjà un backend Express et voulez y brancher Astro, choisissez middleware.

Étape 3 : build et exécution

npm run build

Après le build, dist/ contient un dossier server/ avec entry.mjs — point d’entrée du serveur SSR.

Lancer le serveur :

node ./dist/server/entry.mjs

Par défaut : http://localhost:4321. Toutes les pages passent en SSR.

Débogage en développement

Pas besoin de rebuild à chaque fois :

npm run dev

Le serveur de dev gère le SSR ; les modifications sont prises en compte à chaud.

Dépannage courant

1. Port occupé : si 4321 est pris :

   PORT=3000 node ./dist/server/entry.mjs

2. Module adaptateur introuvable : vérifiez @astrojs/node, relancez npm install

3. Page 404 : vérifiez src/pages/ — les règles de routage Astro s’appliquent aussi en SSR

En pratique, ma première config SSR a pris moins de cinq minutes. Sur Vercel ou Netlify, des adaptateurs dédiés simplifient encore le déploiement — chapitre suivant.

Chapitre 3 : Adaptateurs principaux en détail

Vercel, Netlify, Cloudflare : comment choisir ?

Si le projet est hébergé sur Vercel, Netlify ou Cloudflare, le SSR se configure souvent plus vite. Chaque plateforme a un adaptateur officiel Astro, avec déploiement quasi sans friction.

Adaptateur Vercel — référence en serverless

Vercel est ma plateforme la plus utilisée : quota gratuit correct pour les projets perso, config minimale :

npx astro add vercel

Tout est configuré automatiquement. Exemple de fichier :

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

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Fonctionnalité Vercel : ISR (Incremental Static Regeneration)

Propre à Vercel : une page SSR peut se comporter comme du SSG en cache. Premier accès → rendu SSR ; puis cache pendant un délai ; régénération à l’expiration.

adapter: vercel({
  isr: {
    expiration: 60, // Cache 60 secondes
  },
}),

Pour un site d’actualités, une mise à jour par minute suffit souvent — pas besoin de requête base à chaque hit. ISR combine flexibilité SSR et vitesse proche du statique.

Déploiement Vercel :

1. Configurer l’adaptateur
2. Pousser le code sur GitHub
3. Importer le projet dans la console Vercel
4. Commande de build : npm run build (détection auto)
5. Déployer

Adaptateur Netlify — Edge Functions

Netlify convient bien au duo site statique + fonctions dynamiques.

npx astro add netlify

Configuration :

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

export default defineConfig({
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true, // Active le middleware Edge
  }),
});

Qu’est-ce que edgeMiddleware ?

Exécuter la logique middleware (auth, redirections) sur les nœuds edge — latence réduite. Utile pour la géolocalisation (langue selon la région de l’utilisateur).

Redirections Netlify

Créez un fichier _redirects à la racine, par exemple :

/old-page  /new-page  301

Les redirections s’appliquent au déploiement, sans toucher au code.

Adaptateur Cloudflare — CDN mondial

Pour une audience mondiale, Cloudflare Workers tournent dans 300+ datacenters — latence très basse.

npx astro add cloudflare

Configuration :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Limites Cloudflare

L’environnement Workers n’est pas Node.js complet : certaines API Node (ex. fs) ne sont pas disponibles. Si le projet en dépend fortement, Cloudflare peut ne pas convenir.

Tableau comparatif des adaptateurs

Recommandations :

• Blog, documentation : Vercel ou Netlify en priorité — gratuit souvent suffisant, déploiement simple
• E-commerce, SaaS : Vercel (ISR) ou Node.js auto-hébergé (contrôle total)
• Produit international : Cloudflare (accélération globale)
• Entreprise : Node.js auto-hébergé (données, souveraineté)

Pas de choix absolu : ça dépend du trafic, du budget et des contraintes. Mon blog est sur Vercel ; certains sites clients tournent en Node.js auto-hébergé — les deux fonctionnent bien.

Chapitre 4 : Mode hybride en pratique

SSR et SSG dans un même projet

Après le SSR pur, le point fort : le mode hybride. C’est là qu’Astro brille — vitesse SSG et flexibilité SSR ensemble.

Configurer le mode hybride

Changez output en 'hybrid' :

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

export default defineConfig({
  output: 'hybrid', // SSG par défaut, SSR à la demande
  adapter: node(),
});

Par défaut, toutes les pages restent en SSG. Pour une page dynamique, une ligne dans le frontmatter suffit.

Contrôle au niveau page

Comment activer le SSR sur une page ? Dans le frontmatter :

// src/pages/dashboard.astro (SSR)

---

export const prerender = false; // Pas de pré-rendu → SSR
const user = Astro.cookies.get('user');

---

<h1>Bon retour, {user?.name}</h1>
<p>Vous avez {user?.notifications} messages non lus</p>

prerender = false signifie : ne pas générer au build, rendre à la visite.

À l’inverse, avec output: 'server' (tout en SSR), pour forcer le SSG sur une page :

// src/pages/about.astro (SSG)

---

export const prerender = true; // Génération au build

---

<h1>À propos</h1>
<p>Contenu fixe, pré-généré, chargement très rapide.</p>

Récapitulatif (à ne pas inverser) :

Au début j’inversais souvent ; la règle : hybrid = SSG d’abord, server = SSR d’abord.

Cas pratique : blog + espace utilisateur

Structure type pour un blog avec connexion :

Arborescence :

src/pages/
├── index.astro          // Accueil (SSG)
├── about.astro          // À propos (SSG)
├── blog/
│   ├── [slug].astro     // Article (SSG)
│   └── index.astro      // Liste articles (SSG)
├── login.astro          // Connexion (SSR)
├── dashboard.astro      // Espace utilisateur (SSR)
└── api/
    └── comments.js      // API commentaires (SSR)

Configuration :

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // SSG par défaut
  adapter: vercel(), // Déploiement Vercel
});

Page statique (sans config spéciale) :

// src/pages/blog/[slug].astro

---

// Pas de prerender → SSG par défaut en mode hybrid
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

---

<article>
  <h1>{post.data.title}</h1>
  <div set:html={post.body} />
</article>

Page dynamique (SSR) :

// src/pages/dashboard.astro

---

export const prerender = false; // Active le SSR

// Vérifier la connexion
const token = Astro.cookies.get('token')?.value;
if (!token) {
  return Astro.redirect('/login');
}

// Récupérer l'utilisateur depuis l'API
const user = await fetch(`https://api.example.com/user`, {
  headers: { Authorization: `Bearer ${token}` }
}).then(res => res.json());

---

<div>
  <h1>Bienvenue, {user.name}</h1>
  <p>E-mail : {user.email}</p>
  <p>Dernière connexion : {user.lastLogin}</p>
</div>

Route API (SSR automatique) :

// src/pages/api/comments.js
export async function POST({ request }) {
  const { articleId, content } = await request.json();

  // Enregistrer le commentaire
  await db.comments.insert({
    articleId,
    content,
    createdAt: new Date(),
  });

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' }
  });
}

export async function GET({ url }) {
  const articleId = url.searchParams.get('articleId');

  const comments = await db.comments.findMany({
    where: { articleId },
    orderBy: { createdAt: 'desc' }
  });

  return new Response(JSON.stringify(comments), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Bénéfices :

1. Pages statiques (articles, accueil) : toujours très rapides, Lighthouse 95+, CDN
2. Pages dynamiques (espace utilisateur) : données fraîches par utilisateur
3. Routes API : backend intégré sans serveur séparé
4. Build court : seules les pages statiques sont pré-rendues

Sur un projet récent — une cinquantaine d’articles + espace membre — le build a pris environ 20 secondes. Pages statiques instantanées, pages dynamiques souvent sous 100 ms. Le hybride est vraiment le bon compromis par défaut.

Chapitre 5 : Problèmes fréquents et bonnes pratiques

Pièges de configuration SSR et solutions

Voici les erreurs que j’ai rencontrées, avec les correctifs, pour éviter les mêmes écueils.

Problème 1 : Astro.clientAddress is only available when using output: 'server'

Cause : utilisation de Astro.clientAddress (IP client) alors que output reste 'static'.

Solution :

// astro.config.mjs
export default defineConfig({
  output: 'server', // ou 'hybrid'
  adapter: node(),
});

Astro.clientAddress, Astro.cookies, Astro.redirect() ne fonctionnent qu’en mode SSR (ou hybride avec page non pré-rendue).

Problème 2 : 404 en production, OK en local

Cause : mauvais adaptateur ou commande de build / répertoire de sortie incorrect sur la plateforme.

Solutions :

Vercel :

• Build : npm run build
• Sortie : .vercel/output (automatique)
• Ne pas surcharger les routes dans vercel.json — laisser Astro gérer

Netlify :

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

• Build : npm run build
• Publication : dist (statique) ou .netlify (SSR)
• Si 404 persiste, vérifier netlify.toml :

  [build]
    command = "npm run build"
    publish = "dist"

Problème 3 : page SSR lente (> 2 s)

Cause : serveur sous-dimensionné ou requêtes base lentes.

Solutions :

1. Cache :

   // src/pages/api/news.js
   export async function GET() {
     const cached = await redis.get('news');
     if (cached) {
       return new Response(cached, {
         headers: {
           'Content-Type': 'application/json',
           'Cache-Control': 'public, max-age=60' // Cache 60 s
         }
       });
     }
   
     const news = await fetchNewsFromDB();
     await redis.set('news', JSON.stringify(news), 'EX', 60);
   
     return new Response(JSON.stringify(news), {
       headers: {
         'Content-Type': 'application/json',
         'Cache-Control': 'public, max-age=60'
       }
     });
   }

2. Optimiser les requêtes :

   • Index sur les colonnes filtrées
   • Moins de JOIN inutiles
   • Sélectionner uniquement les champs nécessaires

3. ISR sur Vercel :

   adapter: vercel({
     isr: { expiration: 300 } // Cache 5 minutes
   }),

Problème 4 : variables d’environnement absentes côté client

Cause : Astro distingue variables serveur et client.

Solution :

Côté serveur (pages SSR, routes API) :

const secret = import.meta.env.SECRET_KEY; // Toute variable d'env

Côté client (JavaScript dans le navigateur) :

const apiUrl = import.meta.env.PUBLIC_API_URL; // Préfixe PUBLIC_ obligatoire

Fichier .env :

SECRET_KEY=abc123          # Serveur uniquement
PUBLIC_API_URL=https://api.example.com  # Client et serveur

Problème 5 : adapter.setApp is not a function

Cause : versions Astro et adaptateur incompatibles.

Solution :

# Mettre à jour
npm update astro @astrojs/node

# Ou versions alignées (voir la doc officielle)
npm install astro@latest @astrojs/node@latest

En général, garder Astro et l’adaptateur à jour suffit.

Synthèse des bonnes pratiques

1. Hybride par défaut : sauf projet 100 % dynamique, output: 'hybrid'
2. SSR ciblé : prerender = false seulement où c’est nécessaire
3. Assets statiques via CDN : public/ pour images, CSS, JS
4. Cache / ISR : listes peu volatiles (actualités) pour soulager le serveur
5. Séparer les secrets : variables sensibles côté serveur ; config publique avec PUBLIC_
6. Surveiller : Vercel Analytics ou Google Analytics sur le temps de réponse SSR

Conclusion

En trois idées :

1. Le SSR n’est pas universel — utilisez-le à bon escient

Ne vous précipitez pas sur le SSR ni ne déclarez le SSG obsolète. Statique en SSG, dynamique en SSR ; pour la plupart des projets, le hybride est le meilleur équilibre. J’ai vu des blogs entièrement passés en SSR : performances en baisse, alors que le contenu ne change pas — le SSG via CDN reste plus rapide.

2. L’adaptateur suit la plateforme — la config est simple

Sur Vercel/Netlify/Cloudflare : npx astro add [platform]. En auto-hébergé : npx astro add node, environ cinq minutes. La pratique est plus directe que la doc ne le suggère.

3. Le mode hybride combine vitesse et personnalisation

C’est l’essence d’Astro : pages statiques avec Lighthouse 95+, pages dynamiques personnalisées, build et coûts maîtrisés. Pour mes nouveaux projets, le hybride est le premier choix.

Prochaines étapes

Après cette lecture :

1. Essayer tout de suite : npx astro add node sur votre projet Astro — cinq minutes pour toucher au SSR
2. Lister vos besoins : quelles pages doivent être dynamiques, lesquelles restent statiques
3. Aller plus loin : les Server Islands d’Astro permettent d’embarquer des composants SSR dans une page SSG — encore plus flexible

En cas de blocage, la communauté Discord Astro répond vite et accueille bien les questions.

Dernier rappel : évitez la sur-ingénierie. Avec un trafic modeste (< 10 000 PV/jour), un site statique peut suffire — le SSR ajoute de la complexité sans gain métier évident. La technique doit servir le produit, pas l’inverse.

Bon déploiement — et n’hésitez pas à laisser un commentaire si vous bloquez sur un point précis.