Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to

Use Clerk with Gatsby

Learn how to use Clerk to quickly and easily add secure authentication and user management to your Gatsby application.

Install gatsby-plugin-clerk

Once you have a React application ready, you need to install Clerk's React SDK. This gives you access to our prebuilt components and hooks for React applications.

npm install gatsby-plugin-clerk
yarn add gatsby-plugin-clerk
pnpm add gatsby-plugin-clerk

Set environment keys

Below is an example of your .env.development file.

Pro tip! If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the API Keys(opens in a new tab) page.


Update gatsby-config.ts

To use Clerk, you will need to update your gatsby-config.ts in order to resolve gatsby-plugin-clerk and load from .env files.

import type { GatsbyConfig } from "gatsby" require("dotenv").config({ path: `.env.${process.env.NODE_ENV}`, }) const config: GatsbyConfig = { siteMetadata: { title: `clerk-test`, siteUrl: `https://www.yourdomain.tld`, }, // Add Gatsby plugin plugins: [ { resolve: `gatsby-plugin-clerk` }, ], } export default config

Protecting your pages

Clerk offers Control 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.

import React from 'react' import { SignIn, SignedIn, RedirectToSignIn, SignedOut, UserButton } from 'gatsby-plugin-clerk' export default function IndexPage() { return ( <> <SignedIn> <UserButton /> </SignedIn> <SignedOut> <RedirectToSignIn /> </SignedOut> </> ) }

Read sesssion and user data

Clerk provides a set of hooks and helpers that you can use to access the active session and user data in your React application. Here are examples of how to use these helpers.


The useAuth hook is a convenient way to access the current auth state. This hook provides the minimal information needed for data-loading and helper methods to manage the current active session.

import { useAuth } from "gatsby-plugin-clerk"; export default function Example() { const { isLoaded, userId, sessionId, getToken } = useAuth(); // In case the user signs out while on the page. if (!isLoaded || !userId) { return null; } return ( <div> Hello, {userId} your current active session is {sessionId} </div> ); }


The useUser hook is a convenient way to access the current user data where you need it. This hook provides the user data and helper methods to manage the current active session.

import { useUser } from "gatsby-plugin-clerk"; export default function Example() { const { isLoaded, isSignedIn, user } = useUser(); if (!isLoaded || !isSignedIn) { return null; } return <div>Hello, {user.firstName} welcome to Clerk</div>; }

SSR usage

import * as React from 'react'; import { GetServerData } from 'gatsby'; import { withServerAuth } from 'gatsby-plugin-clerk/ssr'; export const getServerData: GetServerData<any> = withServerAuth( async props => { return { props: { data: '1', auth: props.auth } }; }, { loadUser: true }, ); function SSRPage({ serverData }: any) { return ( <main> <h1>SSR Page with Dogs</h1> <pre>{JSON.stringify(serverData, null, 2)}</pre> </main> ); } export default SSRPage;

Next steps

Now that you have an application integrated with Clerk, you will want to read the following documentation:

Customization & Localization

Learn how to customize and localize the Clerk components.

Learn More

Authentication Components

Learn more about all our authentication components.

Learn More

Client Side Helpers

Learn more about our client side helpers and how to use them.

Learn More

Last updated on February 13, 2024

What did you think of this content?

Clerk © 2024