clerk-astro-patterns

Astro のパターン

SDK：@clerk/astro v4 以降。Astro 5 以降が必要です。

何が必要ですか？

タスク	リファレンス
ミドルウェアを設定する（基本の clerkMiddleware()、ページごとのチェック）	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 と 静的プリレンダリング の 2 つのレンダリングモードがあります。Clerk の動作はそれぞれで異なります。

• SSR ページ — ミドルウェアによって設定される Astro.locals.auth() を使います
• 静的ページ（export const prerender = true）— Clerk ミドルウェアはこれらのページをスキップするため、アイランドでクライアントサイドフックを使います
• アイランド — React／Vue／Svelte コンポーネントです。@clerk/astro/react の useAuth() やその他のフックを使います

Request → clerkMiddleware() → SSR page → Astro.locals.auth()
                                ↓
                         Island (.client) → useAuth() hook

セットアップ

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 } from '@clerk/astro/server'

export const onRequest = clerkMiddleware()

ミドルウェアは Astro.locals.auth() を設定します。各ページと API ルートで、それぞれ認証をチェックします。createRouteMatcher は @clerk/astro 4.0 で削除されました（3.x で非推奨）。追加しないでください。既存の使用箇所は、アップグレード前にページと API ルートのチェックに移行する必要があります。Astro の clerkMiddleware() リファレンスを参照してください。

SSR ページの認証

---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---

<h1>Dashboard</h1>

API ルートの認証

// src/pages/api/data.ts
import type { APIRoute } from 'astro'

export const GET: APIRoute = ({ locals }) => {
  const { userId } = locals.auth()
  if (!userId) return new Response('Unauthorized', { status: 401 })

  return Response.json({ userId })
}

よくある落とし穴

症状	原因	修正方法
Astro.locals.auth が未定義	ミドルウェアがありません	src/middleware.ts に clerkMiddleware を追加します
開発環境では認証が機能するが、本番環境では機能しない	グローバル設定が output: 'static'	保護するページでは output: 'server' または hybrid を設定します
静的ページで認証が機能しない	プリレンダリングされたページではミドルウェアがスキップされます	export const prerender = false を使うか、アイランドに移します
アイランドがサインインに反応しない	client:load ディレクティブがありません	アイランドコンポーネントに client:load を追加します

インポートマップ

用途	インポート元
clerkMiddleware、clerkClient	@clerk/astro/server
useAuth、UserButton（useUser はありません）	@clerk/astro/react
$userStore、$authStore	@clerk/astro/client
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 組織

ドキュメント

Astro SDK