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

Clerk's Gatsby SDK has prebuilt components, React hooks, and helpers to make user authentication easier.

To get started using Clerk with Gatsby, add the SDK to your project:

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

Set environment variables

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 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"

  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 {
  } from 'gatsby-plugin-clerk'

export default function IndexPage() {
  return (
        <UserButton />
        <RedirectToSignIn />

Read session 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 (
      Hello, {userId} your current active session is {sessionId}


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>;
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 (
      <h1>SSR Page with Dogs</h1>
      <pre>{JSON.stringify(serverData, null, 2)}</pre>

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.

Authentication Components

Learn more about all our authentication components.

Client Side Helpers

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


What did you think of this content?