Meet our Gatsby plugin

Learn how to add authentication and user management to your Gatsby app with Clerk.

At Clerk, our mission is to empower every developer to easily add authentication and user management to their apps.

We know it's hard to keep up with all the exciting new options out there, so we strive to create more tools and integrations, so you, the developer, can spend more time building what really matters: your app.

With that in mind, we're happy to announce our gatsby-plugin-clerk.

What it does

The plugin wraps our ClerkProvider component around the entire Gatsby app.

This has two benefits: keeping the layout component cleaner while grouping all the configuration in gatsby-config.js, alongside other plugins.

How to use it

First and foremost, install the necessary packages:

yarn add gatsby-plugin-clerk @clerk/clerk-react

# or

npm install gatsby-plugin-clerk @clerk/clerk-react

Now, let's configure the plugin on gatsby-config.js.

For this step, you'll need the frontendApi key of your Clerk application. To find it, go to your dashboard, choose the application and the instance you're working on, and locate the key on the Home tab.

// gatsby-config.js

module.exports =  {
    plugins:  [
        {
            resolve:  'gatsby-plugin-clerk',
            options:  {
                // OBS: Don't push your frontend API key to version control.
                // A safer approach is to set it as an environment variable for each environment your app will run in.
                frontendApi:  <YOUR_FRONTEND_API_KEY>
            }
        }
    ]
}

From here onwards, everything should work just the same. You can start using components like SignedIn and SignedOut from the root of your app.

// src/pages/index.js

import React from  'react'
import { SignIn, SignedIn, SignedOut, UserButton } from '@clerk/clerk-react'

function IndexPage() {
    return  (
        <>
            <SignedIn>
                <UserButton />
            </SignedIn>

            <SignedOut>
                <SignIn />
            </SignedOut>
        </>
    )
}

export default IndexPage

And that's it, in just a few steps, we added easy and secure authentication with beautiful and complete user management to your Gatsby app.

Bonus: Clerk + Gatsby starter

To make it even easier for you, we went ahead and created a Clerk + Gatsby starter repository. It has Clerk integrated with Gatsby's default starter.

Inside src/api you can also find the new Gatsby Functions in action. We added a couple of examples there, so you know how to use Gatsby's serverless functions with Clerk's backend API.

Fork it, clone it and build it!

Bonus 2: Deploy the starter on Gatsby Cloud

Ok, we owe this one to the Gatsby team. They did a great job in building a super easy deployment flow.

So, if you want to deploy the Clerk + Gatsby starter on Gatsby Cloud, just click here.

Once there, you can configure a number of things, like the Gatsby Cloud workspace the project should live in, the repository name that will be created in your GitHub account, and even add more integrations.

But here's the one thing you can't forget: your need to add your environment variables, like in the image below. If you don't know where to find them, check the README file of this starter.

Once you're done, head over to your GitHub account, find the newly created repository, clone it and start building.

And just like this, you can use all the benefits and performance that Gatsby Cloud provides to Gatsby apps.

If you encounter a permissions error while doing the steps above, here's what's happening: Gatsby Cloud requires permissions to create and manage future repositories on your GitHub account in order to create a new repository for you.

To fix it, go to your GitHub installations page, and configure Gatsby Cloud as such:

Need help?

If you're unfamiliar with how our prebuilt UI components or other details described in the guide work, you can always go to our documentation to find out more or reach out to us on our Discord server.

Happy coding!