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 にはページごとに 2 つのレンダリングモードがあります: SSR と 静的プリレンダリング。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 が未定義 | ミドルウェアがない | clerkMiddleware を src/middleware.ts に追加 |
| 開発では認証が機能するが本番では機能しない | グローバルに 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 組織