clerk-astro-patterns

Create src/middleware.ts exporting onRequest from clerkMiddleware, and use createRouteMatcher to match protected paths like /dashboard(.*). Inside the handler, call auth().redirectToSignIn() when the route matches and auth().userId is falsy, otherwise return next().

Call Astro.locals.auth() in the page frontmatter to destructure userId, orgId, and other fields. Redirect with Astro.redirect('/sign-in') when userId is missing. The page must not have export const prerender = true for server auth to work.

Astro.locals.auth is undefined when clerkMiddleware is missing from src/middleware.ts, since the middleware is what populates the auth object. It also fails on statically prerendered pages because middleware is skipped for pages with export const prerender = true.

No, Clerk middleware skips pages with export const prerender = true, so Astro.locals.auth() is unavailable there. Either set export const prerender = false to make the page SSR, or use client-side hooks like useAuth inside a hydrated island component.

Import components like UserButton, SignInButton, and Show from @clerk/astro/react, not @clerk/astro/components. Mount the component in your .astro file with a client:load directive, since without hydration Clerk hooks return undefined and the UI is not reactive.

In your API route handler, call context.locals.auth() to get userId and return new Response('Unauthorized', { status: 401 }) when it is falsy. Use 403 for authenticated users lacking permissions, checked via auth.has({ permission: '...' }).