skilld
All skills
clerk avatar

/clerk-astro-patterns

@932e2dd official
by clerkclerk/skills83 stars
5

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-astro-patterns

This session only. Nothing lands on disk.

SKILL.md

≈66 tokens always: the name and description. ≈731 when used: this file. ≈3.8k more on demand in 8 files.

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

Source: SKILL.md on GitHub

Third-party checks

No alerts16d4 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill provides safe documentation, templates, and patterns for integrating Clerk authentication with the Astro framework. No security issues, malicious code, or unsafe data practices were detected.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 932e2dd. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated 6 months ago

Capability

What it can do
Network
metadata
{
  "author": "clerk",
  "version": "1.0.0"
}
All 1 allowed tools
WebFetch

Topics

  • TypeScript
  • astro
  • clerk
  • authentication
  • middleware
  • ssr
  • api-routes
  • island-components

README badge

README badge for clerk/skills/clerk-astro-patterns

What it does

Provides Clerk authentication patterns for Astro projects using @clerk/astro v3+, covering middleware setup, SSR page protection, island components, and API route auth across Astro's static and server rendering modes. Includes import paths, config examples, and a troubleshooting table for common integration issues.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with static Astro sites?
Partially. Clerk middleware skips static prerendered pages; you must use `export const prerender = false` or move authentication logic to client-side island components with `client:load`.
What Astro and Clerk SDK versions are required?
Astro 4.15 or later and @clerk/astro v3 or later.
How do I protect pages with authentication?
Use `clerkMiddleware` in `src/middleware.ts` with `createRouteMatcher` to define protected routes, then check `auth().userId` and redirect to sign-in if needed. For SSR pages, retrieve auth from `Astro.locals.auth()`.
Can I use Clerk in React island components?
Yes. Import hooks like `useAuth()` and `useUser()` from `@clerk/astro/react`, and ensure the island component has the `client:load` directive.
Why is `Astro.locals.auth` undefined?
The Clerk middleware is missing. Add `clerkMiddleware` and `onRequest` to `src/middleware.ts`.

Generated from the current SKILL.md. These answers refresh after source changes.