Astro Quickstart
Use this prebuilt prompt to get started faster.
Example repository
Create a new Astro app
If you don't already have an Astro app, run the following commands to create a new one.
npm create astro@latest clerk-astro
cd clerk-astropnpm create astro clerk-astro
cd clerk-astroyarn create astro clerk-astro
cd clerk-astrobunx create-astro clerk-astro
cd clerk-astroInstall @clerk/astro
The Clerk Astro SDK gives you access to a set of components, hooks, and stores to make user authentication easier.
Run the following command to install the SDK:
npm install astro@6 @astrojs/node@10 @clerk/astropnpm add astro@6 @astrojs/node@10 @clerk/astroyarn add astro@6 @astrojs/node@10 @clerk/astrobun add astro@6 @astrojs/node@10 @clerk/astroIf you're adding Clerk to an existing app on Astro 4.15+, 5, or 6:
- Run
npm install @clerk/astroinstead, and keep your Astro version and adapter. - If you need an adapter, install the
@astrojs/nodemajor that matches your Astro version (v10 for Astro 6, v9 for Astro 5). Don't runnpx astro add node— it installs the Astro 7-only latest.
Set your Clerk API keys
Add the following keys to your .env file. These keys can always be retrieved from the API keys page in the Clerk Dashboard.
PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEYUpdate astro.config.mjs
To configure Clerk in your Astro app, you will need to update your astro.config.mjs.
- Add the
clerk()integration to theintegrationslist. For a list of available options, see the integration reference. - Add an SSR adapter. This quickstart uses the
@astrojs/nodeadapter, which you installed in the Install@clerk/astrostep. If you already have one, keep it. - Set
outputtoserver. This is required when deploying to a host supporting SSR.
import { defineConfig } from 'astro/config'
import node from '@astrojs/node'
import clerk from '@clerk/astro'
export default defineConfig({
integrations: [clerk()],
adapter: node({ mode: 'standalone' }),
output: 'server',
})Add clerkMiddleware() to your app
clerkMiddleware() grants you access to user authentication state throughout your app. To add clerkMiddleware() to your app, follow these steps:
- Create a
middleware.tsfile.- If you're using the
/srcdirectory, createmiddleware.tsin the/srcdirectory. - If you're not using the
/srcdirectory, createmiddleware.tsin the root directory.
- If you're using the
- In your
middleware.tsfile, export anonRequestconstant and assign the result of theclerkMiddleware()function to it.src /middleware.ts import { clerkMiddleware } from '@clerk/astro/server' export const onRequest = clerkMiddleware() - By default,
clerkMiddleware()will not protect any routes. All routes are public and you must opt-in to protection. To require a signed-in user, protect resources close to where they're used, as shown in the guide on reading user data.
Create a header with Clerk components
You can control which content signed-in and signed-out users can see with Clerk's prebuilt control components. The following example creates a header using the following components:
- <Show when="signed-in">: Children of this component can only be seen while signed in.
- <Show when="signed-out">: Children of this component can only be seen while signed out.
- <UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
- <SignInButton />: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
- <SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.
---
import { Show, UserButton, SignInButton, SignUpButton } from '@clerk/astro/components'
const { title } = Astro.props
---
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="generator" content={Astro.generator} />
<title>{title}</title>
</head>
<body>
<header>
<Show when="signed-out">
<SignInButton mode="modal" />
<SignUpButton mode="modal" />
</Show>
<Show when="signed-in">
<UserButton />
</Show>
</header>
<slot />
</body>
</html>
<style>
html,
body {
margin: 0;
width: 100%;
height: 100%;
}
</style>Then, use the layout on your homepage:
---
import Layout from '../layouts/Layout.astro'
import { Show } from '@clerk/astro/components'
---
<Layout title="Clerk + Astro">
<Show when="signed-out">
<p>Sign in to try Clerk out!</p>
</Show>
<Show when="signed-in">
<p>You are signed in!</p>
</Show>
</Layout>Run your project
Run your project with the following command:
npm run devpnpm run devyarn devbun run devCreate your first user
- Visit your app's homepage at http://localhost:4321.
- Select "Sign up" on the page and authenticate to create your first user.
Next steps
Explore the most relevant next steps for your SDK using the following guides.
Prebuilt components
Learn how to add Clerk's prebuilt authentication and user-management UI to your app.
Build custom flows
Learn how to build custom user interfaces entirely from scratch using the Clerk API.
Read user data
Learn how to use Clerk's helpers to read user data in your app.
Configure clerkMiddleware()
Learn how to integrate Clerk authentication into your Astro app through middleware.
More to explore
Explore additional Clerk features that help you build, manage, and grow your application.
- Organizations - Organizations are shared accounts that let teams collaborate, manage members and roles, and control access to shared resources.
- Billing - Billing enables you to manage subscriptions, free trials, payments, plans, and billing-related webhook events for B2C and B2B applications.
- Waitlist - Waitlist lets you collect signups and control access to new products or features before launch through a simple, integrated workflow.
Feedback
Last updated on