Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

Gatsby Authentication

Learn to install and initialize Clerk in a new Gatsby application.

Overview

Clerk is the easiest way to add authentication and user management to your Gatsby application. This guide will walk you through the necessary steps to install and use Clerk in a new Gatsby application. After following this guide, you should have a working Gatsby app complete with:

  • Fully fledged sign in and sign up flows.
  • Google Social Login.
  • Secure email/password authentication.
  • A prebuilt user profile page.

Before you start

You need to create a Clerk Application in your Clerk Dashboard.

Create a new Gatsby app

Start by creating a new Gatsby application - this is usually done using the npx gatsby new CLI:

npx gatsby new

Choose a directory to create the app and follow the terminal prompts to set up your app with your preferred options.

Installing the plugin

1
# Install the necessary Clerk packages
2
npm install gatsby-plugin-clerk

Add your environment variables.

To use Clerk with Gatsby, you will need to use the publishable key, and secret key found in the Dashboard added to your .env.development

.env.development
1

Update gatsby.config.js

Make sure you add the following snippet to be able to load environment variables.:

1
import type { GatsbyConfig } from "gatsby"
2


3
// add dotenv loading
4
require("dotenv").config({
5
  path: `.env.${process.env.NODE_ENV}`,
6
})
7
const config: GatsbyConfig = {
8
  siteMetadata: {
9
    title: `clerk-test`,
10
    siteUrl: `https://www.yourdomain.tld`,
11
  },
12
  graphqlTypegen: true,
13
  
14
  // add gatsby plugin
15
  plugins: [
16
    {
17
      resolve: `gatsby-plugin-clerk`
18
    },
19
  ],
20
}
21


22
export default config
23

Using the plugin

Client-side

Client-side components are imported directly from gatsby-plugin-clerk. 

1
import React from 'react'
2
import {
3
  SignIn,
4
  SignedIn,
5
  SignedOut,
6
  UserButton
7
  } from 'gatsby-plugin-clerk'
8


9
export default function IndexPage() {
10
  return (
11
    <>
12
      <SignedIn>
13
        <UserButton />
14
      </SignedIn>
15
      <SignedOut>
16
        <SignIn />
17
      </SignedOut>
18
    </>
19
  )
20
}

Server-Side Rendering (SSR)

You can also use Gatsby SSR using withServerAuth from 'gatsby-plugin-clerk/ssr'. 

1
import * as React from 'react';
2
import { GetServerData } from 'gatsby';
3
import { withServerAuth } from 'gatsby-plugin-clerk/ssr';
4


5
export const getServerData: GetServerData<any> = withServerAuth(
6
  async props => {
7
    return { props: { data: '1', auth: props.auth } };
8
  },
9
  { loadUser: true },
10
);
11


12
function SSRPage({ serverData }: any) {
13
  return (
14
    <main>
15
      <h1>SSR Page with Clerk</h1>
16
      <pre>{JSON.stringify(serverData, null, 2)}</pre>
17
    </main>
18
  );
19
}
20


21
export default SSRPage;

Server API routes

Importing 'gatsby-plugin-clerk/api' gives access to all the exports coming from @clerk/sdk-node. 

1
import { clerkClient, withAuth } from 'gatsby-plugin-clerk/api';
2


3
interface ContactBody {
4
  message: string;
5
}
6


7
const handler = withAuth(async (req, res) => {
8
  const users = await clerkClient.users.getUserList();
9
  res.send({ title: `We have ${users.length} users`, message: req.body.message, auth: req.auth });
10
});
11


12
export default handler;

Next steps

Was this helpful?

Clerk © 2023