How do I install the Clerk Astro Patterns skill?

Run npx skillmds@latest add kintsugi-programmer/clerk-astro-patterns in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Clerk Astro Patterns safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts, makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Clerk Astro Patterns?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Clerk Astro Patterns free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Clerk Astro Patterns?

kintsugi-programmer (@kintsugi-programmer) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Clerk Astro Patterns by kintsugi-programmer

Name: Clerk Astro Patterns
Rating: 4.2 (5 reviews)
Author: kintsugi-programmer

Clerk Astro Patterns

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

kintsugi-programmer Updated Sep 8, 2026 0 repo stars

File contents

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

Docs

Astro SDK

---name: clerk-astro-patternsdescription: Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.license: MIT---# Astro PatternsSDK: `@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 ModelAstro 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```tsimport { defineConfig } from 'astro/config'import clerk from '@clerk/astro'export default defineConfig({ integrations: [clerk()], output: 'server',})```### src/middleware.ts```tsimport { 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```astro---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```# .envPUBLIC_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](https://clerk.com/docs/astro/getting-started/quickstart)

Frequently asked questions