Patrons Astro
SDK : @clerk/astro v3+. Nécessite Astro 4.15+.
De quoi avez-vous besoin ?
| Tâche | Référence |
|---|---|
| Configurer le middleware | references/middleware.md |
| Protéger les pages SSR | references/ssr-pages.md |
| Utiliser Clerk dans les composants îlots | references/island-components.md |
| Authentification dans les routes API | references/api-routes.md |
| Utiliser Clerk avec React dans Astro | references/astro-react.md |
Modèle mental
Astro propose deux modes de rendu par page : SSR et prerender statique. Clerk fonctionne différemment dans chaque mode :
- Pages SSR — utiliser
Astro.locals.auth()qui est alimenté par le middleware - Pages statiques (
export const prerender = true) — le middleware Clerk les ignore ; utiliser les hooks côté client dans les îlots - Îlots — composants React/Vue/Svelte ; utiliser
useAuth()et autres hooks de@clerk/astro/react
Requête → clerkMiddleware() → page SSR → Astro.locals.auth()
↓
Îlot (.client) → hook useAuth()
Configuration
astro.config.mjs
import { defineConfig } from 'astro/config'
import clerk from '@clerk/astro'
export default defineConfig({
integrations: [clerk()],
output: 'server',
})
src/middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)'])
export const onRequest = clerkMiddleware((auth, context, next) => {
if (isProtectedRoute(context.request) && !auth().userId) {
return auth().redirectToSignIn()
}
return next()
})
Authentification sur les pages SSR
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>Tableau de bord</h1>
Pièges courants
| Symptôme | Cause | Correctif |
|---|---|---|
Astro.locals.auth est indéfini | Middleware manquant | Ajouter clerkMiddleware dans src/middleware.ts |
| L'auth fonctionne en dev mais pas en production | output: 'static' globalement | Définir output: 'server' ou hybrid pour les pages protégées |
| La page statique n'a pas d'auth | Les pages pré-rendues ignorent le middleware | Utiliser export const prerender = false ou déplacer dans un îlot |
| L'îlot ne réagit pas à la connexion | Directive client:load manquante | Ajouter client:load au composant îlot |
Carte d'importation
| Élément | Importer depuis |
|---|---|
clerkMiddleware, createRouteMatcher | @clerk/astro/server |
useAuth, useUser, UserButton | @clerk/astro/react |
Composants Astro (<SignIn>, etc.) | @clerk/astro/components |
Variables d'environnement
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro utilise le préfixe PUBLIC_ pour les variables exposées au client (pas NEXT_PUBLIC_).
Voir aussi
clerk-setup- Installation initiale de Clerkclerk-custom-ui- Flux personnalisés et apparenceclerk-orgs- Organisations B2B