Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-astro-patterns

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

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.

  • 14 files
  • 21 KB
  • MIT
  • Updated last week
  • GitHub
Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-astro-patterns

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈66 tokens for metadata: the name and description. ≈886 when used: this file. ≈4.1k more on demand in 8 files.

Description uses 3.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈264 characters, or 3.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Astro Patterns

SDK: @clerk/astro v4+. Requires Astro 5+.

What Do You Need?

Task Reference
Configure middleware (bare clerkMiddleware(), checks per page) 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 } from '@clerk/astro/server'

export const onRequest = clerkMiddleware()

The middleware populates Astro.locals.auth(). Each page and API route checks for itself. createRouteMatcher was removed in @clerk/astro 4.0 (deprecated in 3.x). Don't add it. Existing uses must move to page and API-route checks before upgrading. See the Astro clerkMiddleware() reference.

SSR Page Auth

---
const { userId, orgId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
---

<h1>Dashboard</h1>

API Route Auth

// src/pages/api/data.ts
import type { APIRoute } from 'astro'

export const GET: APIRoute = ({ locals }) => {
  const { userId } = locals.auth()
  if (!userId) return new Response('Unauthorized', { status: 401 })

  return Response.json({ userId })
}

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, clerkClient @clerk/astro/server
useAuth, UserButton (no useUser) @clerk/astro/react
$userStore, $authStore @clerk/astro/client
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

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

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

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Network
metadata
{
  "author": "clerk",
  "version": "1.0.0"
}
All 1 allowed tools
WebFetch
  • TypeScript
  • astro
  • clerk
  • authentication
  • middleware
  • ssr
  • api-routes
  • island-components

README badge

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

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.

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.