` from older versions.
Basic usage:
```astro
---
import { Show } from '@clerk/astro/components'
---
You are signed in.
Please sign in.
```
Role and permission gating:
```astro
Admin panel
Billing
```
Function predicate for compound checks:
```astro
has({ role: 'org:admin' }) || has({ permission: 'org:billing:manage' })}>
Billing
```
When the page is prerendered in a `server`-output app (or vice versa), add the `isStatic` prop so `` reads from the client nanostores instead of `locals`:
```astro
```
### Customizing Clerk components
Two levers control appearance: the `appearance` prop on the `clerk()` integration (app-wide defaults) and the `appearance` prop on individual components (overrides).
#### Appearance prop basics
Global appearance lives on the integration:
```ts
// astro.config.mjs
import { defineConfig } from 'astro/config'
import node from '@astrojs/node'
import clerk from '@clerk/astro'
import { dark } from '@clerk/themes'
export default defineConfig({
integrations: [
clerk({
appearance: {
baseTheme: dark,
variables: { colorPrimary: '#6c47ff' },
elements: {
formButtonPrimary: 'bg-indigo-600 hover:bg-indigo-700',
},
},
}),
],
adapter: node({ mode: 'standalone' }),
output: 'server',
})
```
#### Theming to match your Astro site
Pass a `baseTheme` from `@clerk/themes` (e.g. `dark`, `neobrutalism`) for quick themed looks. Use `variables` for CSS-level changes (primary color, border radius, font). Use `elements` to inject class names on Clerk's internal DOM — useful for projects that ship Tailwind classes.
> Put appearance on the `clerk()` integration for app-wide defaults. Override per-component only when a specific mount needs to look different — for example, a dark-themed `` on a light marketing page.
### Building custom UI with Clerk's stores and hooks
The prebuilt components cover most cases. When you need a fully custom sign-in flow, an inline profile editor, or a dashboard that reads auth state in a non-standard way, drop to the stores or hooks.
#### When to use stores or hooks instead of components
Common reasons:
- You need a sign-in UI that is pixel-identical to an existing design system.
- You want to read user data inside a client island without re-rendering the whole auth shell.
- You need to trigger auth actions imperatively (for example, on a button click outside a Clerk component).
#### Accessing auth state in Astro islands via nanostores
Nanostores are framework-agnostic. Use `@nanostores/react`, `@nanostores/vue`, `@nanostores/svelte`, or the raw `useStore` helper from `nanostores` directly.
```tsx
// src/components/ProfileCard.tsx
import { useStore } from '@nanostores/react'
import { $userStore } from '@clerk/astro/client'
export default function ProfileCard() {
const user = useStore($userStore)
if (user === undefined) return Loading...
if (user === null) return Signed out.
return Signed in as {user.firstName}.
}
```
Mount it as a React island with `client:load`:
```astro
---
import ProfileCard from '../components/ProfileCard.tsx'
---
```
#### Using `useAuth` in React islands
The `@clerk/astro/react` subpath ships one hook — `useAuth` — alongside React versions of the Clerk components. It returns the same auth primitives available in `.astro` frontmatter (`isLoaded`, `isSignedIn`, `userId`, `sessionId`, `orgId`, `orgRole`, `has`, `getToken`, `signOut`) and needs a React island with a `client:*` directive to work:
```tsx
// src/components/Greeting.tsx
import { useAuth } from '@clerk/astro/react'
import { useStore } from '@nanostores/react'
import { $userStore } from '@clerk/astro/client'
export default function Greeting() {
const { isLoaded, isSignedIn } = useAuth()
const user = useStore($userStore)
if (!isLoaded) return Loading...
if (!isSignedIn) return Please sign in.
return Hello, {user?.firstName}.
}
```
Pair `useAuth` with the relevant nanostore when you need full resources — `$userStore` for the user record, `$organizationStore` for the active organization, `$sessionStore` for the session, and `$signInStore` or `$signUpStore` for in-progress auth flows.
> `useAuth` and the nanostores only work inside client-side islands. In `.astro` frontmatter, use `Astro.locals.auth()` on the server. Mixing the client-only helpers into `.astro` frontmatter will throw at build time.
## Protecting routes with Astro middleware
Middleware is the single place to enforce auth across many routes at once. Clerk's `clerkMiddleware()` wraps Astro's middleware API and adds route matching, auth population, and redirects.
### How Astro middleware works
`src/middleware.ts` exports `onRequest` (preferred) or a default export. The function receives an `APIContext` and a `next` callback. It runs on every SSR request, before the page renders:
```ts
// src/middleware.ts — vanilla Astro middleware
import { defineMiddleware } from 'astro:middleware'
export const onRequest = defineMiddleware(async (context, next) => {
context.locals.startedAt = Date.now()
const response = await next()
return response
})
```
Access `context.request`, `context.cookies`, `context.locals`, `context.redirect()`, `context.rewrite()`, and `context.url`. Compose middleware with `sequence()`:
```ts
import { sequence } from 'astro:middleware'
import { clerkMiddleware } from '@clerk/astro/server'
export const onRequest = sequence(clerkMiddleware(), myOtherMiddleware)
```
> Middleware only runs on SSR requests. Prerendered pages bypass middleware entirely — the HTML was baked at build time and never hits your server. Any route that needs auth must be SSR.
### Adding Clerk's clerkMiddleware()
The minimal setup:
```ts
// src/middleware.ts
import { clerkMiddleware } from '@clerk/astro/server'
export const onRequest = clerkMiddleware()
```
By default, every route is **public**. The middleware populates `Astro.locals.auth()` and `Astro.locals.currentUser()` on every SSR request whether the route is protected or not — protecting is opt-in.
### Defining protected routes
There are two patterns. Opt-in (default public, list the protected routes) is simpler. Opt-out (default protected, list the public routes) is safer for B2B apps where missing a protection is worse than a user seeing an unexpected sign-in page.
#### Protecting pages
Use `createRouteMatcher()` to describe protected paths, then redirect unauthenticated visitors inside the middleware callback:
```ts
// src/middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/orgs/(.*)'])
export const onRequest = clerkMiddleware((auth, context) => {
const { isAuthenticated, redirectToSignIn } = auth()
if (!isAuthenticated && isProtectedRoute(context.request)) {
return redirectToSignIn()
}
})
```
The matcher syntax is Express-style. `(.*)` matches everything after the prefix, so `/dashboard(.*)` covers `/dashboard`, `/dashboard/team`, and so on.
#### Protecting API endpoints
API routes return JSON, so redirecting to a sign-in page does not help a JSON client. `@clerk/astro` has no `protect()` helper — the `auth` parameter is a function that returns the auth object, so check `auth().isAuthenticated` and return a `401` `Response` yourself for unauthenticated API requests:
```ts
// src/middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'
const isApiRoute = createRouteMatcher(['/api/(.*)'])
export const onRequest = clerkMiddleware((auth, context) => {
if (isApiRoute(context.request) && !auth().isAuthenticated) {
return new Response(JSON.stringify({ error: 'Unauthorized' }), {
status: 401,
headers: { 'Content-Type': 'application/json' },
})
}
})
```
You can also enforce auth inside the endpoint itself by reading `Astro.locals.auth()` in the route handler and returning a `401` there — handy when only a few endpoints need protection.
#### Route matchers for public vs private
The opt-out pattern protects everything and lists exceptions:
```ts
// src/middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'
const isPublicRoute = createRouteMatcher([
'/',
'/sign-in(.*)',
'/sign-up(.*)',
'/pricing',
'/blog(.*)',
])
export const onRequest = clerkMiddleware((auth, context) => {
const { isAuthenticated, redirectToSignIn } = auth()
if (!isPublicRoute(context.request) && !isAuthenticated) {
return redirectToSignIn()
}
})
```
This is safer for B2B dashboards: every new route you add is protected by default. You have to explicitly add it to the public list to expose it.
### Handling SSR and prerendered pages
Prerendered pages do not run middleware. If you need auth on a mostly-static site, two options:
1. Switch to `output: 'server'` and mark static pages with `export const prerender = true`.
2. Stay on `output: 'static'` and mark auth routes with `export const prerender = false`. Middleware runs for those routes only.
The first option is usually cleaner for apps where most pages need auth. The second fits marketing sites with a single logged-in portal.
### Redirect behavior for unauthenticated users
`redirectToSignIn()` sends unauthenticated visitors to your sign-in URL and appends a `redirect_url` query parameter so they return to their original destination after signing in. Configure that URL with the `signInUrl` option on the `clerk()` integration or the `PUBLIC_CLERK_SIGN_IN_URL` environment variable — for example, `PUBLIC_CLERK_SIGN_IN_URL=/sign-in` to use the in-app `/sign-in` route from earlier. Without it, Clerk falls back to its hosted Account Portal sign-in page.
To override the return destination Clerk appends — where the user lands after signing in — pass `returnBackUrl`:
```ts
return auth().redirectToSignIn({ returnBackUrl: '/dashboard' })
```
> Always allow `/sign-in(.*)` and `/sign-up(.*)` through your protection check. If the sign-in page itself redirects unauthenticated visitors to `/sign-in`, you get an infinite redirect loop. The opt-out pattern above shows the correct shape.
## Conclusion
With the Clerk Astro SDK configured, you can build powerful authentication flows and secure pages with minimal boilerplate. Prebuilt components like `` and `` get you to production quickly, while the client-side nanostores and React hooks give you the flexibility to build entirely custom UIs when needed. Astro middleware ties it all together, ensuring that protected routes remain secure whether you are building a server-rendered dashboard or a hybrid static site.
In the next part of this series, we will dive into the core mechanics of session management, building multi-tenant dashboards with Organizations, and implementing role-based access control (RBAC).
## Frequently asked questions
## FAQ
### Does Clerk support Astro's SSR and SSG rendering modes?
Yes — both `output: 'server'` and `output: 'static'`. Pass `isStatic={true}` to control components on prerendered pages, omit it on SSR pages. Middleware runs only on SSR requests, so any auth-aware page must be SSR: `export const prerender = false` in a `static` app, or `export const prerender = true` for marketing pages in a `server` app.
### How do I use Clerk's nanostores in Astro islands?
Use `@nanostores/react`, `@nanostores/vue`, or `@nanostores/svelte` to subscribe to `$authStore`, `$userStore`, and others from `@clerk/astro/client`. These stores provide framework-agnostic reactive state inside client islands. Always handle the initial `undefined` loading state to avoid hydration mismatches.
## In this series
1. [Authentication for Astro Sites](https://clerk.com/articles/authentication-for-astro-sites.md)
2. **Authentication for Astro Sites - Part 2** (you are here)
3. [Authentication for Astro Sites - Part 3](https://clerk.com/articles/authentication-for-astro-sites-3.md)
4. [Authentication for Astro Sites - Part 4](https://clerk.com/articles/authentication-for-astro-sites-4.md)