Docs

Astro Quickstart

You will learn the following:

  • Install @clerk/astro
  • Set up your environment keys to test your app locally
  • Add TypeScript declarations
  • Add the clerk() integration to your application
  • Use Clerk middleware to implement route-specific authentication
  • Create a header with Clerk components for users to sign in and out

Before you start

Example repository

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

Install @clerk/astro

Add Clerk's Astro SDK to your project:

terminal
npm install @clerk/astro
terminal
yarn add @clerk/astro
terminal
pnpm add @clerk/astro

Set environment variables

.env
PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Update astro.config.mjs

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

  • Add the Clerk integration to the integrations list.
  • Install an SSR adapter. For this quickstart we chose the @astrojs/node adapter. You can use any Node based adapter you wish.
  • 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 middleware to your application

clerkMiddleware() grants you access to user authentication state throughout your application, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your application, follow these steps:

  1. Create a middleware.ts file inside your src/ directory.

  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() reference to learn how to require authentication for specific routes.

Add TypeScript declarations

Update the env.d.ts file in your src/ directory to add type definitions for the locals added by the middleware.

src/env.d.ts
/// <reference types="astro/client" />
/// <reference types="@clerk/astro/env" />

Add components to your app

Clerk offers components that allow you to protect your pages. These components are used to control the visibility of your pages based on the user's authentication state.

src/layouts/SiteLayout.astro
---
import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components'
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <header>
      <h1>{title}</h1>
      <nav>
        <SignedOut>
          <SignInButton mode="modal" />
        </SignedOut>
        <SignedIn>
          <UserButton />
        </SignedIn>
      </nav>
    </header>
    <article>
      <slot />
    </article>
  </body>
</html>
src/pages/index.astro
---
import SiteLayout from '../layouts/SiteLayout.astro'
---

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

Create your first user

Run your project with the following command:

terminal
npm run dev
terminal
yarn dev
terminal
pnpm 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 application.

Clerk + Astro Quickstart Repo

The official companion repo for Clerk's Astro Quickstart.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on