Astro-Muster
SDK: @clerk/astro v3+. Erfordert Astro 4.15+.
Was wird benötigt?
| Aufgabe | Referenz |
|---|---|
| Middleware konfigurieren | references/middleware.md |
| SSR-Seiten schützen | references/ssr-pages.md |
| Clerk in Island-Komponenten verwenden | references/island-components.md |
| Authentifizierung in API-Routen | references/api-routes.md |
| Clerk mit React in Astro verwenden | references/astro-react.md |
Mentales Modell
Astro bietet zwei Rendermodi pro Seite: SSR und statisches Pre-Rendering. Clerk arbeitet in jedem Modus anders:
- SSR-Seiten – verwenden
Astro.locals.auth(), das von der Middleware bereitgestellt wird - Statische Seiten (
export const prerender = true) – die Clerk-Middleware überspringt sie; verwende clientseitige Hooks in Islands - Islands – React/Vue/Svelte-Komponenten; verwende
useAuth()und andere Hooks aus@clerk/astro/react
Anfrage → clerkMiddleware() → SSR-Seite → Astro.locals.auth()
↓
Island (.client) → useAuth()-Hook
Einrichtung
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()
})
SSR-Seiten-Authentifizierung
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>Dashboard</h1>
Häufige Fehlerquellen
| Symptom | Ursache | Lösung |
|---|---|---|
Astro.locals.auth ist undefined | Fehlende Middleware | Füge clerkMiddleware in src/middleware.ts hinzu |
| Authentifizierung funktioniert in der Entwicklung, aber nicht in der Produktion | output: 'static' global gesetzt | Setze output: 'server' oder hybrid für geschützte Seiten |
| Statische Seite hat keine Authentifizierung | Vorgerenderte Seiten überspringen die Middleware | Verwende export const prerender = false oder verlagere in eine Island |
| Island reagiert nicht auf Anmeldung | Fehlende client:load-Direktive | Füge client:load zur Island-Komponente hinzu |
Import-Übersicht
| Was | Import von |
|---|---|
clerkMiddleware, createRouteMatcher | @clerk/astro/server |
useAuth, useUser, UserButton | @clerk/astro/react |
Astro-Komponenten (<SignIn>, usw.) | @clerk/astro/components |
Umgebungsvariablen
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro verwendet das Präfix PUBLIC_ für clientseitig zugängliche Variablen (nicht NEXT_PUBLIC_).
Siehe auch
clerk-setup– Ersteinrichtung von Clerkclerk-custom-ui– Benutzerdefinierte Abläufe und Erscheinungsbildclerk-orgs– B2B-Organisationen