skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
midudev/autoskills58 installs

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.

How do I install this agent skill?

npx skills add https://github.com/midudev/autoskills --skill clerk-astro-patterns
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides a comprehensive set of templates and instructions for integrating Clerk authentication into Astro applications, following industry best practices for security and implementation.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Astro Patterns

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

What Do You Need?

TaskReference
Configure middleware (bare clerkMiddleware(), checks per page)references/middleware.md
Protect SSR pagesreferences/ssr-pages.md
Use Clerk in island componentsreferences/island-components.md
Auth in API routesreferences/api-routes.md
Use Clerk with React in Astroreferences/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

SymptomCauseFix
Astro.locals.auth is undefinedMissing middlewareAdd clerkMiddleware to src/middleware.ts
Auth works in dev but not productionoutput: 'static' globallySet output: 'server' or hybrid for protected pages
Static page has no authPrerendered pages skip middlewareUse export const prerender = false or move to island
Island not reactive to sign-inMissing client:load directiveAdd client:load to the island component

Import Map

WhatImport 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

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/midudev/autoskills/clerk-astro-patterns">View clerk-astro-patterns on skillZs</a>