Astro Patterns

SDK: @clerk/astro v3+. Requiert Astro 4.15+.

Ce dont vous avez 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 island	references/island-components.md
Auth dans les routes API	references/api-routes.md
Utiliser Clerk avec React dans Astro	references/astro-react.md

Modèle mental

Astro dispose de deux modes de rendu par page : SSR et prerender statique. Clerk fonctionne différemment dans chacun :

Pages SSR — utilisez Astro.locals.auth() qui est renseignée par le middleware
Pages statiques (export const prerender = true) — le middleware Clerk les ignore ; utilisez les hooks côté client dans les islands
Islands — composants React/Vue/Svelte ; utilisez useAuth() et autres hooks de @clerk/astro/react

Request → clerkMiddleware() → SSR page → Astro.locals.auth()
                                ↓
                         Island (.client) → useAuth() hook

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()
})

Auth sur page SSR

---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---

<h1>Dashboard</h1>

Pièges courants

Symptôme	Cause	Solution
`Astro.locals.auth` est undefined	Middleware manquant	Ajoutez `clerkMiddleware` à `src/middleware.ts`
Auth fonctionne en dev mais pas en production	`output: 'static'` globalement	Définissez `output: 'server'` ou `hybrid` pour les pages protégées
Page statique sans auth	Les pages prerendues ignorent le middleware	Utilisez `export const prerender = false` ou déplacez vers une island
Island non réactive à la connexion	Directive `client:load` manquante	Ajoutez `client:load` au composant island

Import Map

Quoi	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 Clerk
clerk-custom-ui - Flux personnalisés et apparence
clerk-orgs - Organisations B2B

Docs

Astro SDK

clerk-astro-patterns