skills.rest
divinaarmuela
divinaarmuelaCOMMUNITY
Explore all skills by this author →
GitHub

clerk-astro-patterns

Implements Clerk authentication patterns for Astro middleware, SSR pages, islands, and API routes.

Updated Apr 19, 2026
Search Tags:#authentication#middleware#astro#ssr#api routes#clerk#island components
One-click install
npx skills add https://github.com/divinaarmuela/Content --skill clerk-astro-patterns-divinaarmuela
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: clerk-astro-patterns
Source: https://github.com/divinaarmuela/Content/tree/main/.claude/skills/clerk-astro-patterns
Command: npx skills add https://github.com/divinaarmuela/Content --skill clerk-astro-patterns-divinaarmuela

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @clerk/astro, astro, @astrojs/node, @astrojs/react, and includes references (resource) components.

What problem does it solve? Integrating Clerk authentication into Astro apps is tricky because Astro has two rendering modes (SSR and static prerender) plus island components, and auth behaves differently in each. This Skill provides the correct patterns for middleware, SSR pages, islands, and API routes so auth works reliably across all rendering modes. ## Core Features & Use Cases - Middleware Setup: Configure clerkMiddleware with createRouteMatcher to protect routes like /dashboard and redirect unauthenticated users to sign-in. - SSR & API Route Auth: Use Astro.locals.auth() in server-rendered pages and context.locals.auth() in API endpoints, with proper 401/403 status codes and org/permission checks. - Island Components: Use useAuth, UserButton, and SignInButton from @clerk/astro/react with client:load hydration for client-side auth state. - Use Case: You are building an Astro app with a mix of static marketing pages and a protected dashboard. Use this Skill to set up middleware that guards /dashboard, read the user ID in SSR pages, and add a React header island that shows SignInButton or UserButton based on sign-in state. ## Quick Start Set up Clerk middleware in my Astro app to protect the /dashboard route and redirect unauthenticated users to /sign-in.

Frequently Asked Questions about clerk-astro-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I protect routes with Clerk middleware in Astro?▼

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().

How do I get the current user in an Astro SSR page with Clerk?▼

Call Astro.locals.auth() in the page frontmatter to destructure userId, orgId, and other fields. Redirect with Astro.redirect('/sign-in') when userId is falsy. The page must not have export const prerender = true, since prerendered pages skip middleware.

Why is Astro.locals.auth undefined in my Astro app?▼

Astro.locals.auth is undefined when clerkMiddleware is missing from src/middleware.ts, or when the page is statically prerendered since middleware is skipped for prerendered pages. Add the middleware and set output to 'server' or 'hybrid' in astro.config.mjs.

Can I use Clerk React components in Astro islands?▼

Yes, import useAuth, UserButton, and SignInButton from @clerk/astro/react (not @clerk/react) and mount the component with a client:load directive. Without a client directive the island is server-rendered only and Clerk hooks return undefined.

Does Clerk auth work on statically prerendered Astro pages?▼

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

How do I authenticate Astro API routes with Clerk?▼

In the API route handler, call context.locals.auth() to get userId and return new Response('Unauthorized', { status: 401 }) when it is falsy. API routes are always SSR, and you can also check org membership or permissions with auth.has() returning 403 when unauthorized.

Related Skills

Explore More Software Engineering Skills→
sudarshan-krishnansudarshan-krishnan

clerk-setup

Add Clerk authentication to web apps and APIs by framework.

Community
Advanced
Rajaryan1726Rajaryan1726

clerk-orgs

Implement Clerk Organizations for multi-tenant B2B apps with roles, invitations, and enterprise SSO.

Community
Advanced
sheriaxsheriax

clerk-custom-ui

Create custom Clerk authentication flows and theme components with React hooks.

Official
Intermediate
sheriaxsheriax

clerk-nextjs-patterns

Implement Clerk authentication patterns in Next.js with middleware and Server Actions.

Official
Advanced