@clerk/astro

@clerk/astro

Changelog · Report a Bug · Request a Feature · Ask a Question

---

Overview

Clerk is the easiest way to add authentication and user management to your Astro application. Add sign up, sign in, and profile management to your Astro application in minutes.

Getting Started

Prerequisites

• Astro 3.2 or later
• Node.js >=18.17.0 or later

Installation

Add @clerk/astro as a dependency

With npm

npm install @clerk/astro

With yarn

yarn add @clerk/astro

With pnpm

pnpm add @clerk/astro

Build

To build the package locally with the TypeScript compiler, run:

npm run build

To build the package in watch mode, run the following:

npm run dev

Usage

Set environment variables

PUBLIC_ASTRO_APP_CLERK_PUBLISHABLE_KEY=pk_(test|live)_xxxxxxx
CLERK_SECRET_KEY=sk_(test|live)_xxxxxxx

PUBLIC_ASTRO_APP_CLERK_SIGN_IN_URL=/sign-in # update this if sign in page exists on another path
PUBLIC_ASTRO_APP_CLERK_SIGN_UP_URL=/sign-up # update this if sign up page exists on another path

Update env.d.ts

/// <reference types="astro/client" />
/// <reference types="@clerk/astro/env" />

Add integrations

• Add the clerk integration in your astro.config.mjs file.
• (Optional) Install the @astrojs/react and add the react in your astro.config.mjs file. You only need to perform this action if you are planing to use react with your project or the React features that provided by astro-clerk-auth. Instructions
• Install the @astrojs/node package and the node adapter in your astro.config.mjs file. Instructions
• Set output to server.

Example configuration file

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import node from '@astrojs/node';
import clerk from '@clerk/astro';

export default defineConfig({
  integrations: [
    react(),
    clerk({
      afterSignInUrl: '/',
      afterSignUpUrl: '/',
    }),
  ],
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

Add a middleware file

This step is required in order to use SSR or any control component. Create a middleware.ts file inside the src/ directory.

Simple use

import { clerkMiddleware } from '@clerk/astro/server';

export const onRequest = clerkMiddleware();

Supports chaining with sequence

const greeting = defineMiddleware(async (context, next) => {
  console.log('greeting request');
  console.log(context.locals.auth());
  const response = await next();
  console.log('greeting response');
  return response;
});

export const onRequest = sequence(clerkMiddleware(), greeting);

Advanced use with handler

const isProtectedPage = createRouteMatcher(['/user(.*)', '/discover(.*)', /^\/organization/]);

export const onRequest = clerkMiddleware((auth, context, next) => {
  const requestURL = new URL(context.request.url);
  if (['/sign-in', '/', '/sign-up'].includes(requestURL.pathname)) {
    return next();
  }

  if (isProtectedPage(context.request) && !auth().userId) {
    return auth().redirectToSignIn();
  }

  if (!auth().orgId && requestURL.pathname !== '/discover' && requestURL.pathname === '/organization') {
    const searchParams = new URLSearchParams({
      redirectUrl: requestURL.href,
    });

    const orgSelection = new URL(`/discover?${searchParams.toString()}`, context.request.url);

    return context.redirect(orgSelection.href);
  }

  return next();
});

Use Clerk UI Components

Supported components

• SignIn
• SignUp
• UseProfile
• UserButton
• CreateOrganization
• OrganizationSwitcher
• OrganizationList
• OrganizationProfile

All of the above can be used with React or Vanilla JS. The only difference is the import path.

// Import UserProfile build with React (requires `@astro/react`)
import { UserProfile } from '@clerk/astro/components/react';

// Import UserButton build with vanilla JS
import { UserProfile } from '@clerk/astro/components/interactive';

Pages that include a Clerk UI component need to be wrapped with ClerkLayout, as shown above.

Use Clerk Control Components

Supported components

• SignedIn
• SignedOut
• Protect

All of the above can be used with React or only on server. The only difference is the import path.

// Import Protect build with React (requires `@astro/react`)
import { Protect } from '@clerk/astro/components/react';

// Import SignedIn build server side code
import { SignedIn } from '@clerk/astro/components/control';

Protect your API Routes

In this example we are fetching the logged in user.

import type { APIRoute } from 'astro';

const unautorized = () =>
  new Response(JSON.stringify({ error: 'unathorized access' }), {
    status: 401,
  });

export const GET: APIRoute = async ({ locals }) => {
  if (!locals.auth().userId) {
    return unautorized();
  }

  return new Response(JSON.stringify(await locals.currentUser()), {
    status: 200,
  });
};

Use Astro.locals

• Use Astro.locals.auth() to retrieve the Authentication Object

Use Clerk react hooks

Example SignedIn React component that supports SSR

import type { PropsWithChildren } from 'react';
import { useAuth } from '@clerk/astro/client/react';

export function SignedIn(props: PropsWithChildren) {
  const { userId } = useAuth();

  if (!userId) {
    return null;
  }
  return props.children;
}

Use a client store to build your custom logic

Warning: SSR not supported

import type { PropsWithChildren } from 'react';
import { useStore } from '@nanostores/react';
import { $authStore } from '@clerk/astro/client/stores';

export function SignedOut(props: PropsWithChildren) {
  const { userId } = useStore($authStore);

  if (userId) {
    return null;
  }
  return props.children;
}

Use Clerk react components inside your components

Example Header react component that uses Clerk components

import { SignedIn, SignedOut, UserButton } from '@clerk/astro/client/react';

export function Header() {
  return (
    <header>
      <h1>My App</h1>
      <SignedIn>
        <UserButton />
      </SignedIn>
      <SignedOut>
        <a href='/sign-in'>Go to Sign in</a>
      </SignedOut>
    </header>
  );
}

Use Clerk in Headless Mode

Clerk Headless mode (see ClerkJSVariant prop their docs) is a Clerk variant that is focused towards getting smaller bundle sizes. This variant does not include React or any client side components for Clerk (e.g. their signin component). Because of that the bundle size is drastically smaller. On top of that it also lazy loads the JavaScript client side.

In order to use headless mode with this package, change your Astro configuration file to:

import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import node from "@astrojs/node";
- import clerk from "@clerk/astro";
+ import clerk from "@clerk/astro/hotload";

export default defineConfig({
  integrations: [
    react(),
    clerk({
+      clerkJSVariant: "headless"
    }),
  ],
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
});

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• Create a GitHub Discussion
• Contact options listed on our Support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines) .

Security

@clerk/astro follows good practices of security, but 100% security cannot be assured.

@clerk/astro is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.