# Astro Quickstart 1. ## Create a new Astro app If you don't already have an Astro app, run the following commands to [create a new one](https://docs.astro.build/en/install-and-setup/). ```npm npm create astro@latest clerk-astro cd clerk-astro ``` 2. ## Install `@clerk/astro` The [Clerk Astro SDK](https://clerk.com/docs/astro/reference/overview.md) gives you access to a set of components, hooks, and stores to make user authentication easier. Run the following command to install the SDK and the [`@astrojs/node`](https://docs.astro.build/en/guides/integrations-guide/node/) adapter, which this quickstart uses: ```npm npm install @astrojs/node @clerk/astro ``` If you're adding Clerk to an existing app, keep your Astro version and adapter — the SDK supports Astro 5, 6, and 7. If you need an adapter, install the `@astrojs/node` major that matches your Astro version (v11 for Astro 7, v10 for Astro 6, v9 for Astro 5). If npm reports a peer conflict, update Astro to its latest minor first — the newest adapter releases require recent Astro minors. If you're on Astro 4, [upgrade to Astro 5](https://docs.astro.build/en/guides/upgrade-to/v5/) or later first — the SDK no longer supports it. 3. ## Set your Clerk API keys Add the following keys to your `.env` file. These keys can always be retrieved from the [**API keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard. If you haven't already, create a new Clerk application in the [Clerk Dashboard](https://dashboard.clerk.com/). For more information, see the [setup guide](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md?sdk=astro). 1. In the Clerk Dashboard, navigate to the [**API keys**](https://dashboard.clerk.com/~/api-keys) page. 2. In the **Quick Copy** section, copy your Clerk Publishable Key and Secret Key. 3. Paste your keys into your `.env` file. The final result should resemble the following: filename: .env ```env PUBLIC_CLERK_PUBLISHABLE_KEY={{pub_key}} CLERK_SECRET_KEY={{secret}} ``` 4. ## 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](https://clerk.com/docs/astro/reference/integration.md). - Add an [SSR adapter](https://docs.astro.build/en/guides/server-side-rendering/#official-adapters). This quickstart uses the [`@astrojs/node`](https://docs.astro.build/en/guides/integrations-guide/node/) adapter, which you installed in the [Install @clerk/astro](https://clerk.com/docs/astro/getting-started/quickstart.md#install-clerk-astro) step. If you already have one, keep it. - Set `output` to `server`. This is required when deploying to a host supporting SSR. filename: astro.config.mjs ```ts 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', }) ``` 5. ## Add `clerkMiddleware()` to your app [clerkMiddleware()](https://clerk.com/docs/astro/reference/clerk-middleware.md) grants you access to user authentication state throughout your app. 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. 2. In your `middleware.ts` file, export an `onRequest` constant and assign the result of the `clerkMiddleware()` function to it. filename: src/middleware.ts ```tsx 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. To require a signed-in user, protect resources close to where they're used, as shown in the [guide on reading user data](https://clerk.com/docs/astro/guides/users/reading.md). 6. ## 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](https://clerk.com/docs/astro/reference/components/overview.md#control-components). The following example creates a header using the following components: - [](https://clerk.com/docs/astro/reference/components/control/show.md): Children of this component can only be seen while **signed in**. - [](https://clerk.com/docs/astro/reference/components/control/show.md): Children of this component can only be seen while **signed out**. - [](https://clerk.com/docs/astro/reference/components/user/user-button.md): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options. - [](https://clerk.com/docs/astro/reference/components/unstyled/sign-in-button.md): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=astro) are set for the sign-in URL, this component links to the [Account Portal sign-in page](https://clerk.com/docs/guides/account-portal/overview.md?sdk=astro#sign-in). - [](https://clerk.com/docs/astro/reference/components/unstyled/sign-up-button.md): An unstyled component that links to the sign-up page. In this example, since no props or [environment variables](https://clerk.com/docs/guides/development/clerk-environment-variables.md?sdk=astro) are set for the sign-up URL, this component links to the [Account Portal sign-up page](https://clerk.com/docs/guides/account-portal/overview.md?sdk=astro#sign-up). filename: src/layouts/Layout.astro ```astro --- import { Show, UserButton, SignInButton, SignUpButton } from '@clerk/astro/components' const { title } = Astro.props --- {title}
``` Then, use the layout on your homepage: filename: src/pages/index.astro ```astro --- import Layout from '../layouts/Layout.astro' import { Show } from '@clerk/astro/components' ---

Sign in to try Clerk out!

You are signed in!

 ``` 7. ## Run your project Run your project with the following command: ```npm npm run dev ``` 8. ## Create your first user 1. Visit your app's homepage at http://localhost:4321. 2. 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](https://clerk.com/docs/reference/components/overview.md?sdk=astro): Learn how to add Clerk's prebuilt authentication and user-management UI to your app. - [Build custom flows](https://clerk.com/docs/guides/development/custom-flows/overview.md?sdk=astro): Learn how to build custom user interfaces entirely from scratch using the Clerk API. - [Read user data](https://clerk.com/docs/guides/users/reading.md?sdk=astro): Learn how to use Clerk's helpers to read user data in your app. - [Configure clerkMiddleware()](https://clerk.com/docs/astro/reference/clerk-middleware.md): 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**](https://clerk.com/docs/guides/organizations/overview.md?sdk=astro) - Organizations are shared accounts that let teams collaborate, manage members and roles, and control access to shared resources. - [**Billing**](https://clerk.com/docs/guides/billing/overview.md?sdk=astro) - Billing enables you to manage subscriptions, free trials, payments, plans, and billing-related webhook events for B2C and B2B applications. - [**Waitlist**](https://clerk.com/docs/guides/secure/restricting-access.md?sdk=astro#waitlist) - Waitlist lets you collect signups and control access to new products or features before launch through a simple, integrated workflow. --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)