Padrões Astro
SDK: @clerk/astro v3+. Requer Astro 4.15+.
O Que Você Precisa?
| Tarefa | Referência |
|---|---|
| Configurar middleware | references/middleware.md |
| Proteger páginas SSR | references/ssr-pages.md |
| Usar Clerk em componentes ilha | references/island-components.md |
| Autenticação em rotas de API | references/api-routes.md |
| Usar Clerk com React no Astro | references/astro-react.md |
Modelo Mental
Astro tem dois modos de renderização por página: SSR e pré-renderização estática. O Clerk funciona de forma diferente em cada um:
- Páginas SSR — use
Astro.locals.auth(), que é populado pelo middleware - Páginas estáticas (
export const prerender = true) — o middleware do Clerk as ignora; use hooks client-side em ilhas - Ilhas — componentes React/Vue/Svelte; use
useAuth()e outros hooks de@clerk/astro/react
Request → clerkMiddleware() → SSR page → Astro.locals.auth()
↓
Island (.client) → useAuth() hook
Configuração
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()
})
Autenticação em Página SSR
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>Dashboard</h1>
Armadilhas Comuns
| Sintoma | Causa | Correção |
|---|---|---|
Astro.locals.auth é undefined | Middleware ausente | Adicione clerkMiddleware em src/middleware.ts |
| Autenticação funciona em dev mas não em produção | output: 'static' globalmente | Defina output: 'server' ou hybrid para páginas protegidas |
| Página estática não tem autenticação | Páginas pré-renderizadas ignoram middleware | Use export const prerender = false ou mova para uma ilha |
| Ilha não reage ao login | Diretiva client:load ausente | Adicione client:load ao componente ilha |
Mapa de Importação
| O Que | Importar De |
|---|---|
clerkMiddleware, createRouteMatcher | @clerk/astro/server |
useAuth, useUser, UserButton | @clerk/astro/react |
Componentes Astro (<SignIn>, etc.) | @clerk/astro/components |
Variáveis de Ambiente
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro usa o prefixo PUBLIC_ para variáveis expostas ao cliente (não NEXT_PUBLIC_).
Veja Também
clerk-setup- Instalação inicial do Clerkclerk-custom-ui- Fluxos personalizados e aparênciaclerk-orgs- Organizações B2B