Astro Quickstart

Before you start

Set up a Clerk application

Example repository

Astro Quickstart Repo

Create a new Astro app

If you don't already have an Astro app, run the following commands to create a new one.

npm

pnpm

yarn

bun

terminal

npm create astro@latest clerk-astro
cd clerk-astro
npm install

terminal

pnpm create astro clerk-astro
cd clerk-astro
pnpm install

terminal

yarn create astro clerk-astro
cd clerk-astro
yarn install

terminal

bunx create-astro clerk-astro
cd clerk-astro
bun install

Install `@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

pnpm

yarn

bun

terminal

npm install @clerk/astro

terminal

pnpm add @clerk/astro

terminal

yarn add @clerk/astro

terminal

bun add @clerk/astro

Set your Clerk API keys

.env

PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Update `astro.config.mjs`

To configure Clerk in your Astro app, you will need to update your astro.config.mjs.

Add the clerk() integration to the integrations list. For a list of available options, see the integration reference.
Install an SSR adapter. This quickstart uses the @astrojs/node adapter.
Set output to server. This is required when deploying to a host supporting SSR.

astro.config.mjs

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. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

Create a middleware.ts file.
- If you're using the /src directory, create middleware.ts in the /src directory.
- If you're not using the /src directory, create middleware.ts in the root directory alongside .env.
In your middleware.ts file, export an onRequest constant and assign the result of the clerkMiddleware() 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 for routes. See the clerkMiddleware() reference to learn how to require authentication for specific routes.

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.

src/layouts/Layout.astro

---
import { Show, UserButton, SignInButton, SignUpButton } from '@clerk/astro/components'
---

<!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>Astro Basics</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:

src/pages/index.astro

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

pnpm

yarn

bun

terminal

npm run dev

terminal

pnpm run dev

terminal

yarn dev

terminal

bun run dev

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

Edit on GitHub

Astro Quickstart

Before you start

Example repository

Create a new Astro app

Install `@clerk/astro`

Set your Clerk API keys

Update `astro.config.mjs`

Add `clerkMiddleware()` to your app

Create a header with Clerk components

Run your project

Create your first user

Next steps

Prebuilt components

Customization & localization

Protect routes using clerkMiddleware()

Protect content and read user data

Use Clerk with Astro and React

Get started with Organizations

Clerk Astro SDK Reference

Astro Quickstart

Before you start

Example repository

Feedback