Astro 패턴
SDK: @clerk/astro v3+. Astro 4.15+ 필요.
필요한 사항
| 작업 | 참고 문서 |
|---|---|
| 미들웨어 구성 | references/middleware.md |
| SSR 페이지 보호 | references/ssr-pages.md |
| 아일랜드 컴포넌트에서 Clerk 사용 | references/island-components.md |
| API 라우트 인증 | references/api-routes.md |
| Astro에서 React와 함께 Clerk 사용 | references/astro-react.md |
개념 모델
Astro는 페이지마다 SSR과 정적 사전 렌더링(static prerender) 두 가지 렌더링 모드를 지원합니다. Clerk은 각 모드에서 다르게 작동합니다.
- SSR 페이지 — 미들웨어가 채워주는
Astro.locals.auth()를 사용합니다. - 정적 페이지 (
export const prerender = true) — Clerk 미들웨어가 이를 건너뜁니다. 아일랜드에서 클라이언트 측 훅을 사용하세요. - 아일랜드 — React/Vue/Svelte 컴포넌트입니다.
@clerk/astro/react의useAuth()및 다른 훅을 사용합니다.
요청 → clerkMiddleware() → SSR 페이지 → Astro.locals.auth()
↓
아일랜드 (.client) → useAuth() 훅
설정
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 페이지 인증
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>대시보드</h1>
일반적인 문제
| 증상 | 원인 | 해결 방법 |
|---|---|---|
Astro.locals.auth가 정의되지 않음 | 미들웨어 누락 | src/middleware.ts에 clerkMiddleware 추가 |
| 개발 환경에서 인증이 작동하지만 프로덕션에서 안 됨 | 전역 output: 'static' 설정 | 보호할 페이지에 대해 output: 'server' 또는 hybrid로 설정 |
| 정적 페이지에 인증 없음 | 사전 렌더링된 페이지는 미들웨어를 건너뜀 | export const prerender = false를 사용하거나 아일랜드로 이동 |
| 아일랜드가 로그인에 반응하지 않음 | client:load 지시어 누락 | 아일랜드 컴포넌트에 client:load 추가 |
가져오기 맵
| 항목 | 가져올 위치 |
|---|---|
clerkMiddleware, createRouteMatcher | @clerk/astro/server |
useAuth, useUser, UserButton | @clerk/astro/react |
Astro 컴포넌트 (<SignIn> 등) | @clerk/astro/components |
환경 변수
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro는 클라이언트 노출 변수에 PUBLIC_ 접두사를 사용합니다 (NEXT_PUBLIC_가 아님).
함께 보기
clerk-setup- 초기 Clerk 설치clerk-custom-ui- 사용자 정의 플로우 및 외관clerk-orgs- B2B 조직