Terminal
Terminal/Skill
Shows how to protect Astro pages and API routes with Clerk, covering middleware, server-rendered pages, and island components.
By Clerk
Works with
npx skills add clerk/skills --skill clerk-astro-patternsSDK: @clerk/astro v4+. Requires Astro 5+.
| Task | Reference |
|---|---|
Configure middleware (bare clerkMiddleware(), checks per page) | references/middleware.md |
| Protect SSR pages | references/ssr-pages.md |
| Use Clerk in island components | references/island-components.md |
| Auth in API routes | references/api-routes.md |
| Use Clerk with React in Astro | references/astro-react.md |
Astro has two rendering modes per page: SSR and static prerender. Clerk works differently in each:
Astro.locals.auth() which is populated by the middlewareexport const prerender = true) — Clerk middleware skips them; use client-side hooks in islandsuseAuth() and other hooks from @clerk/astro/reactRequest → clerkMiddleware() → SSR page → Astro.locals.auth()
↓
Island (.client) → useAuth() hook
import { defineConfig } from 'astro/config'
import clerk from '@clerk/astro'
export default defineConfig({
integrations: [clerk()],
output: 'server',
})
import { clerkMiddleware } from '@clerk/astro/server'
export const onRequest = clerkMiddleware()
The middleware populates Astro.locals.auth(). Each page and API route checks for itself. createRouteMatcher was removed in @clerk/astro 4.0 (deprecated in 3.x). Don't add it. Existing uses must move to page and API-route checks before upgrading. See the Astro clerkMiddleware() reference.
---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---
<h1>Dashboard</h1>
// 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 })
}
| Symptom | Cause | Fix |
|---|---|---|
Astro.locals.auth is undefined | Missing middleware | Add clerkMiddleware to src/middleware.ts |
| Auth works in dev but not production | output: 'static' globally | Set output: 'server' or hybrid for protected pages |
| Static page has no auth | Prerendered pages skip middleware | Use export const prerender = false or move to island |
| Island not reactive to sign-in | Missing client:load directive | Add client:load to the island component |
| What | Import From |
|---|---|
clerkMiddleware, clerkClient | @clerk/astro/server |
useAuth, UserButton (no useUser) | @clerk/astro/react |
$userStore, $authStore | @clerk/astro/client |
Astro components (<SignIn>, etc.) | @clerk/astro/components |
# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...
Astro uses PUBLIC_ prefix for client-exposed variables (not NEXT_PUBLIC_).
clerk-setup - Initial Clerk installclerk-custom-ui - Custom flows & appearanceclerk-orgs - B2B organizations