Patrones de Astro
SDK: @clerk/astro v3+. Requiere Astro 4.15+.
¿Qué necesitas?
| Tarea | Referencia |
|---|---|
| Configurar middleware | references/middleware.md |
| Proteger páginas SSR | references/ssr-pages.md |
| Usar Clerk en componentes isla | references/island-components.md |
| Autenticación en rutas API | references/api-routes.md |
| Usar Clerk con React en Astro | references/astro-react.md |
Modelo mental
Astro tiene dos modos de renderizado por página: SSR y prerenderizado estático. Clerk funciona de manera diferente en cada uno:
- Páginas SSR — usan
Astro.locals.auth()que se completa mediante el middleware - Páginas estáticas (
export const prerender = true) — el middleware de Clerk las omite; usa hooks del lado del cliente en islas - Islas — componentes React/Vue/Svelte; usan
useAuth()y otros hooks de@clerk/astro/react
Request → clerkMiddleware() → SSR page → Astro.locals.auth()
↓
Island (.client) → useAuth() hook
Configuración
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()
})
Autenticación en páginas SSR
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>Dashboard</h1>
Errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
Astro.locals.auth es undefined | Falta middleware | Agrega clerkMiddleware en src/middleware.ts |
| La autenticación funciona en desarrollo pero no en producción | output: 'static' global | Establece output: 'server' o hybrid para las páginas protegidas |
| La página estática no tiene autenticación | Las páginas prerenderizadas omiten el middleware | Usa export const prerender = false o muévelo a una isla |
| La isla no reacciona al inicio de sesión | Falta la directiva client:load | Agrega client:load al componente isla |
Mapa de importaciones
| Qué | Importar desde |
|---|---|
clerkMiddleware, createRouteMatcher | @clerk/astro/server |
useAuth, useUser, UserButton | @clerk/astro/react |
Componentes de Astro (<SignIn>, etc.) | @clerk/astro/components |
Variables de entorno
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro usa el prefijo PUBLIC_ para las variables expuestas al cliente (no NEXT_PUBLIC_).
Ver también
clerk-setup- Instalación inicial de Clerkclerk-custom-ui- Flujos personalizados y aparienciaclerk-orgs- Organizaciones B2B