Skip to main content
Docs

Astro Quickstart

Before you start

Example repository

Install @clerk/astro

The Clerk Astro SDKAstro Icon provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app.

Run the following command to install the SDK:

terminal
npm install @clerk/astro
terminal
yarn add @clerk/astro
terminal
pnpm 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.

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()Astro Icon grants you access to user authentication state throughout your app, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

  1. 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.
  2. 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()
  3. By default, clerkMiddleware() will not protect any routes. All routes are public and you must opt-in to protection for routes. See the clerkMiddleware() referenceAstro Icon to learn how to require authentication for specific routes.

Add Clerk components to your app

You can control which content signed-in and signed-out users can see with Clerk's prebuilt control components. Create a header using the following components:

src/layouts/Layout.astro
---
import { SignedIn, SignedOut, UserButton, SignInButton } 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>Astro Basics</title>
  </head>
  <body>
    <header>
      <h1>{title}</h1>
      <nav>
        <SignedOut>
          <SignInButton mode="modal" />
        </SignedOut>
        <SignedIn>
          <UserButton />
        </SignedIn>
      </nav>
    </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'
---

<Layout title="Clerk + Astro">
  <p>Sign in to try Clerk out!</p>
</Layout>

Create your first user

Run your project with the following command:

terminal
npm run dev
terminal
yarn dev
terminal
pnpm dev
terminal
bun dev

Now visit your app's homepage at http://localhost:4321. Sign up to create your first user.

Next steps

Protect routes using Clerk Middleware

Learn how to protect specific routes from unauthenticated users.

Read session and user data

Learn how to use Clerk's stores and helpers to access the active session and user data in your Astro app.

Clerk + Astro Quickstart Repo

The official companion repo for Clerk's Astro Quickstart.

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on