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

SSR Page Auth

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

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

Docs

Astro SDK

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

SSR Page Auth

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

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

Docs

Astro SDK

Astro Patterns

What Do You Need?

Mental Model

Setup

astro.config.mjs

src/middleware.ts

SSR Page Auth

Common Pitfalls

Import Map

Env Variables

See Also

Docs

Astro Patterns

What Do You Need?

Mental Model

Setup

astro.config.mjs

src/middleware.ts

SSR Page Auth

Common Pitfalls

Import Map

Env Variables

See Also

Docs