Clerk Astro Patterns

Astro Patterns

SDK: @clerk/astro v3+. Requires Astro 4.15+.

What Do You Need?

| Task | Reference |

|------|-----------|

| Configure middleware | 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 |

Mental Model

Astro has two rendering modes per page: SSR and static prerender. Clerk works differently in each:

• SSR pages — use Astro.locals.auth() which is populated by the middleware
• Static pages (export const prerender = true) — Clerk middleware skips them; use client-side hooks in islands
• Islands — React/Vue/Svelte components; use useAuth() and other hooks from @clerk/astro/react

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

Setup

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 Page Auth

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

<h1>Dashboard</h1>

Common Pitfalls

| 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 |

Import Map

| What | Import From |

|------|-------------|

| clerkMiddleware, createRouteMatcher | @clerk/astro/server |

| useAuth, useUser, UserButton | @clerk/astro/react |

| Astro components (<SignIn>, etc.) | @clerk/astro/components |

Env Variables

# .env
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

Astro uses PUBLIC_ prefix for client-exposed variables (not NEXT_PUBLIC_).

See Also

• clerk-setup - Initial Clerk install
• clerk-custom-ui - Custom flows & appearance
• clerk-orgs - B2B organizations

Docs

Astro SDK