Meet our Gatsby plugin
Tags: gatsby, clerk, auth, react
Published: 2021-09-15 16:53:19

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:

```bash 
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](https://dashboard.clerk.dev/), choose the application and the instance you're working on, and locate the key on the Home tab.

```javascript
// 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.

```react
// 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](https://github.com/clerkinc/clerk-gatsby-starter). It has Clerk integrated with [Gatsby's default starter](https://github.com/gatsbyjs/gatsby-starter-default).

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](https://github.com/clerkinc/clerk-gatsby-starter) on Gatsby Cloud, just click [here](https://www.gatsbyjs.com/dashboard/deploynow?url=https://github.com/clerkinc/clerk-gatsby-starter).

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](https://github.com/clerkinc/clerk-gatsby-starter/blob/main/README.md) file of this starter.

![Gatsby Environment Variables](https://clerk.dev/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fe1ql88v4%2Fproduction%2F37292ec19825df500deddefc4a6d70f7c3a52a72-1782x928.png%3Ffit%3Dmax%26auto%3Dformat&w=1920&q=75)

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](https://github.com/settings/installations), and configure Gatsby Cloud as such:*

![Repo Access](https://clerk.dev/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fe1ql88v4%2Fproduction%2F12c63a17a9f99acbc4fa4a623c613da79efac314-1498x546.png%3Ffit%3Dmax%26auto%3Dformat&w=1920&q=75)

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](https://docs.clerk.dev/) to find out more or reach out to us on our [Discord](https://discord.gg/YRHz4h4whV) server.

Happy coding!