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.

referencesssr-pages.md

≈453 tokens on demand. Your agent reads this file only when SKILL.md points to it.

SSR Pages

Basic Auth Check

---
// src/pages/dashboard.astro
const { userId } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')

const data = await fetchData(userId)
---

<h1>Dashboard</h1>
<pre>{JSON.stringify(data)}</pre>

Org-Scoped Page

---
const { userId, orgId, orgRole } = Astro.locals.auth()
if (!userId) return Astro.redirect('/sign-in')
if (!orgId) return Astro.redirect('/select-org')
if (orgRole !== 'org:admin') return Astro.redirect('/dashboard')

const settings = await fetchOrgSettings(orgId)
---

<h1>Org Settings</h1>

Fetch Current User Data

---
import { clerkClient } from '@clerk/astro/server'

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

const client = clerkClient(Astro)
const user = await client.users.getUser(userId)
---

<img src={user.imageUrl} alt={user.fullName ?? ''} />

getToken for External APIs

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

const token = await auth.getToken({ template: 'supabase' })
const data = await fetchFromSupabase(token)
---

Auth Object Fields

Field Type Description
userId string | null Current user ID
orgId string | null Active org ID
orgRole string | null User's role in active org
sessionId string | null Current session ID
has() function Check permissions
getToken() async function Get JWT for external APIs

CRITICAL

  • Astro.locals.auth() returns an auth object — note the () call
  • Pages must NOT have export const prerender = true for server auth to work
  • To opt a single page out of static rendering: export const prerender = false

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 yesterday.

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.