apps/docs/content/docs/guides/authentication/clerk/astro.mdx
Clerk is a drop-in auth provider that handles sign-up, sign-in, user management, and webhooks so you don't have to.
In this guide you'll wire Clerk into a brand-new Astro app and persist users in a Prisma Postgres database. You can find a complete example of this guide on GitHub.
Create a new Astro project:
npm create astro@latest
It will prompt you to customize your setup. Choose the defaults:
:::info
EmptyYesYes:::
Navigate into the newly created project directory:
cd <your-project-name>
Sign in to Clerk and navigate to the home page. From there, press the Create Application button to create a new application. Enter a title, select your sign-in options, and click Create Application.
:::info
For this guide, the Google, Github, and Email sign in options will be used.
:::
Install the Clerk Astro SDK and Node adapter:
npm install @clerk/astro @astrojs/node
In the Clerk Dashboard, navigate to the API keys page. In the Quick Copy section, copy your Clerk Publishable and Secret Keys. Paste your keys into .env in the root of your project:
PUBLIC_CLERK_PUBLISHABLE_KEY=<your-publishable-key>
CLERK_SECRET_KEY=<your-secret-key>
Astro needs to be configured for server-side rendering (SSR) with the Node adapter to work with Clerk. Update your astro.config.mjs file to include the Clerk integration and enable SSR:
import { defineConfig } from "astro/config";
import node from "@astrojs/node"; // [!code ++]
import clerk from "@clerk/astro"; // [!code ++]
export default defineConfig({
integrations: [clerk()], // [!code ++]
adapter: node({ mode: "standalone" }), // [!code ++]
output: "server", // [!code ++]
});
The clerkMiddleware helper enables authentication across your entire application. Create a middleware.ts file in the src directory:
import { clerkMiddleware } from "@clerk/astro/server";
export const onRequest = clerkMiddleware();
Update your src/pages/index.astro file to import the Clerk authentication components:
---
import { // [!code ++]
SignedIn, // [!code ++]
SignedOut, // [!code ++]
UserButton, // [!code ++]
SignInButton, // [!code ++]
} from "@clerk/astro/components"; // [!code ++]
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content="{Astro.generator}" />
<title>Astro</title>
</head>
<body></body>
</html>
Now add a header with conditional rendering to show sign-in buttons for unauthenticated users and a user button for authenticated users:
---
import {
SignedIn,
SignedOut,
UserButton,
SignInButton,
} from "@clerk/astro/components";
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content="{Astro.generator}" />
<title>Astro</title>
</head>
<body>
<header>
// [!code ++]
<SignedOut> // [!code ++] <SignInButton mode="modal" /> // [!code ++] </SignedOut> // [!code
++] <SignedIn> // [!code ++] <UserButton /> // [!code ++] </SignedIn> // [!code ++]
</header>
// [!code ++]
</body>
</html>
To get started with Prisma, you'll need to install a few dependencies:
npm install prisma tsx @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg dotenv pg
:::info
If you are using a different database provider (MySQL, SQL Server, SQLite), install the corresponding driver adapter package instead of @prisma/adapter-pg. For more information, see Database drivers.
:::
Once installed, initialize Prisma in your project:
npx prisma init --db
:::info You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for the database like "My Clerk Astro Project" :::
This will create:
prisma/ directory with a schema.prisma fileprisma.config.ts file with your Prisma configuration.env file with a DATABASE_URL already setAdd a User model that will store authenticated user information from Clerk. The clerkId field uniquely links each database user to their Clerk account:
generator client {
provider = "prisma-client"
output = "../src/generated/prisma"
}
datasource db {
provider = "postgresql"
}
model User { // [!code ++]
id Int @id @default(autoincrement()) // [!code ++]
clerkId String @unique // [!code ++]
email String @unique // [!code ++]
name String? // [!code ++]
} // [!code ++]
Run the following command to create the database tables:
npx prisma migrate dev --name init
After the migration is complete, generate the Prisma Client:
npx prisma generate
This generates the Prisma Client in the src/generated/prisma directory.
Create an env.d.ts file in your src directory to provide TypeScript definitions for your environment variables:
touch src/env.d.ts
Add type definitions for all the environment variables your application uses:
interface ImportMetaEnv {
readonly DATABASE_URL: string;
readonly CLERK_WEBHOOK_SIGNING_SECRET: string;
readonly CLERK_SECRET_KEY: string;
readonly PUBLIC_CLERK_PUBLISHABLE_KEY: string;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
In the src directory, create a lib directory and a prisma.ts file inside it:
mkdir src/lib
touch src/lib/prisma.ts
Initialize the Prisma Client with the PostgreSQL adapter:
import { PrismaClient } from "../generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
const adapter = new PrismaPg({
connectionString: import.meta.env.DATABASE_URL,
});
const prisma = new PrismaClient({
adapter,
});
export default prisma;
Webhooks allow Clerk to notify your application when events occur, such as when a user signs up. You'll create an API route to handle these webhooks and sync user data to your database.
Create the directory structure and file for the webhook endpoint:
mkdir -p src/pages/api/webhooks
touch src/pages/api/webhooks/clerk.ts
Import the necessary dependencies:
import { verifyWebhook } from "@clerk/astro/webhooks";
import type { APIRoute } from "astro";
import prisma from "../../../lib/prisma";
Create the POST handler that Clerk will call. The verifyWebhook function validates that the request actually comes from Clerk using the signing secret:
import { verifyWebhook } from "@clerk/astro/webhooks";
import type { APIRoute } from "astro";
import prisma from "../../../lib/prisma";
export const POST: APIRoute = async ({ request }) => {
// [!code ++]
try {
// [!code ++]
const evt = await verifyWebhook(request, {
// [!code ++]
signingSecret: import.meta.env.CLERK_WEBHOOK_SIGNING_SECRET, // [!code ++]
}); // [!code ++]
const { id } = evt.data; // [!code ++]
const eventType = evt.type; // [!code ++]
console.log(
// [!code ++]
`Received webhook with ID ${id} and event type of ${eventType}`, // [!code ++]
); // [!code ++]
} catch (err) {
// [!code ++]
console.error("Error verifying webhook:", err); // [!code ++]
return new Response("Error verifying webhook", { status: 400 }); // [!code ++]
} // [!code ++]
}; // [!code ++]
When a new user is created, they need to be stored in the database.
You'll do that by checking if the event type is user.created and then using Prisma's upsert method to create a new user if they don't exist:
import { verifyWebhook } from "@clerk/astro/webhooks";
import type { APIRoute } from "astro";
import prisma from "../../../lib/prisma";
export const POST: APIRoute = async ({ request }) => {
try {
const evt = await verifyWebhook(request, {
signingSecret: import.meta.env.CLERK_WEBHOOK_SIGNING_SECRET,
});
const { id } = evt.data;
const eventType = evt.type;
console.log(`Received webhook with ID ${id} and event type of ${eventType}`);
if (eventType === "user.created") {
// [!code ++]
const { id, email_addresses, first_name, last_name } = evt.data; // [!code ++]
await prisma.user.upsert({
// [!code ++]
where: { clerkId: id }, // [!code ++]
update: {}, // [!code ++]
create: {
// [!code ++]
clerkId: id, // [!code ++]
email: email_addresses[0].email_address, // [!code ++]
name: `${first_name} ${last_name}`, // [!code ++]
}, // [!code ++]
}); // [!code ++]
} // [!code ++]
} catch (err) {
console.error("Error verifying webhook:", err);
return new Response("Error verifying webhook", { status: 400 });
}
};
Finally, return a response to Clerk to confirm the webhook was received:
import { verifyWebhook } from "@clerk/astro/webhooks";
import type { APIRoute } from "astro";
import prisma from "../../../lib/prisma";
export const POST: APIRoute = async ({ request }) => {
try {
const evt = await verifyWebhook(request, {
signingSecret: import.meta.env.CLERK_WEBHOOK_SIGNING_SECRET,
});
const { id } = evt.data;
const eventType = evt.type;
console.log(`Received webhook with ID ${id} and event type of ${eventType}`);
if (eventType === "user.created") {
const { id, email_addresses, first_name, last_name } = evt.data;
await prisma.user.upsert({
where: { clerkId: id },
update: {},
create: {
clerkId: id,
email: email_addresses[0].email_address,
name: `${first_name} ${last_name}`,
},
});
}
return new Response("Webhook received", { status: 200 }); // [!code ++]
} catch (err) {
console.error("Error verifying webhook:", err);
return new Response("Error verifying webhook", { status: 400 });
}
};
You'll need to expose your local app for webhooks with ngrok. This will allow Clerk to reach your /api/webhooks/clerk route to push events like user.created.
Start your development server:
npm run dev
In a separate terminal window, install ngrok globally and expose your local app:
npm install --global ngrok
ngrok http 4321
Copy the ngrok Forwarding URL (e.g., https://a65a60261342.ngrok-free.app). This will be used to configure the webhook URL in Clerk.
Astro needs to be configured to accept connections from the ngrok domain. Update your astro.config.mjs to include the ngrok host in the allowed hosts list:
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",
server: {
// [!code ++]
allowedHosts: ["localhost", "<your-ngrok-subdomain>.ngrok-free.app"], // [!code ++]
}, // [!code ++]
});
:::note
Replace <your-ngrok-subdomain> with the subdomain from your ngrok URL. For example, if your ngrok URL is https://a65a60261342.ngrok-free.app, use a65a60261342.ngrok-free.app.
:::
Navigate to the Webhooks section of your Clerk application located near the bottom of the Configure tab under Developers.
Click Add Endpoint and paste the ngrok URL into the Endpoint URL field and add /api/webhooks/clerk to the end. It should look similar to this:
https://a65a60261342.ngrok-free.app/api/webhooks/clerk
Subscribe to the user.created event by checking the box next to it under Message Filtering.
Click Create to save the webhook endpoint.
Copy the Signing Secret and add it to your .env file:
# Prisma
DATABASE_URL=<your-database-url>
# Clerk
PUBLIC_CLERK_PUBLISHABLE_KEY=<your-publishable-key>
CLERK_SECRET_KEY=<your-secret-key>
CLERK_WEBHOOK_SIGNING_SECRET=<your-signing-secret> // [!code ++]
Restart your dev server to pick up the new environment variable:
npm run dev
Navigate to http://localhost:4321 in your browser and sign in using any of the sign-up options you configured in Clerk.
Open Prisma Studio to verify that the user was created in your database:
npx prisma studio
You should see a new user record with the Clerk ID, email, and name from your sign-up.
:::note
If you don't see a user record, there are a few things to check:
/api/webhooks/clerk to the end of the webhook URL.allowedHosts in astro.config.mjs and removed https://.npm run dev for any error messages.:::
You've successfully built an Astro application with Clerk authentication and Prisma, creating a foundation for a secure and scalable full-stack application that handles user management and data persistence with ease.
Now that you have a working Astro app with Clerk authentication and Prisma connected to a Prisma Postgres database, you can: