RedwoodJS Authentication

Learn how to install Clerk in a RedwoodJS application

Overview

RedwoodJS is an opinionated, full-stack web application framework focused on providing an integrated developer experience from build to deployment. It follows standard-based conventions with an eye towards the modern architecture of Jamstack and serverless apps.

Although Redwood contains a built-in authentication system (dbAuth), it requires that you manage the user database yourself and does not provide features like social SSO, passwordless authentication, and multi-session management. Clerk provides these features and more without the hassle of managing your own user auth service.

The Clerk integration with Redwood enables you to focus on building the frontend and GraphQL API aspects of your application without needing to add database fields to the Users table and maintain a secret key to encrypt the session cookie. It’s nice to not have to be concerned with these things.

This guide will walk you through the necessary steps to integrate Clerk as the external authentication provider for RedwoodJS.

Looking for a quickstart? We created a demo app to show you how to add Clerk to your project.

Getting started

The first step is to create a new Clerk application from your Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social login providers you prefer. For more information, check out our Set up your application guide.

After your Clerk application has been created, retrieve your API keys from the API Keys page.

In your Redwood app directory, create a .env file (if one does not currently exist) and set the following environment variables to the respective values from your Clerk dashboard:

1
CLERK_API_KEY=<YOUR_BACKEND_API_KEY>
2
CLERK_FRONTEND_API_URL=<YOUR_FRONTEND_API_KEY>

In order for the Frontend API to be accessible to the Web side in production, you need to add CLERK_FRONTEND_API_URL to the includeEnvironmentVariables array in the redwood.toml file:

1
[web]
2
includeEnvironmentVariables = ['CLERK_FRONTEND_API_URL']

Set up auth

The next step is to run a Redwood CLI command to install the required packages and generate some boilerplate code:

yarn rw setup auth clerk --force

Note: The --force flag is needed to overwrite the existing dbAuth logic.

You should see terminal output similar to the following:

✔ Generating auth lib...
✔ Successfully wrote file `./api/src/lib/auth.js`
✔ Adding auth config to web...
✔ Adding auth config to GraphQL API...
✔ Adding required web packages...
✔ Adding required api packages...
✔ Installing packages...
✔ One more thing...
You will need to add two environment variables with your Clerk URL and API key.
Check out web/src/App.{js,tsx} for the variables you need to add.
See also: <https://redwoodjs.com/docs/authentication#clerk>

If you already followed the instructions to add your environment variables, you should be all set. If you didn’t, add them now.

In your code editor of choice, open up web/src/App.tsx (or App.js if you’re not using TypeScript).

Wrap the Redwood <AuthProvider type="clerk"> component with <ClerkAuthProvider>

1
const App = () => (
2
<FatalErrorBoundary page={FatalErrorPage}>
3
<RedwoodProvider titleTemplate="%PageTitle | %AppTitle">
4
<ClerkAuthProvider>
5
<AuthProvider type="clerk">
6
<RedwoodApolloProvider>
7
<Routes />
8
</RedwoodApolloProvider>
9
</AuthProvider>
10
</ClerkAuthProvider>
11
</RedwoodProvider>
12
</FatalErrorBoundary>
13
)

Add Clerk components and hooks

Now that Clerk auth is set up, restart the dev server with yarn rw dev. If you had the dev server running, it must be restarted to read the newly added environment variables.

You can now access Clerk functions through the Redwood useAuth() hook or you can use the Clerk components directly.

For example, you can write:

1
import { useAuth } from '@redwoodjs/auth'
2
3
const HomePage = () => {
4
const { currentUser, isAuthenticated, logIn, logOut } = useAuth()
5
6
return (
7
<>
8
{isAuthenticated ? (
9
<button onClick={logOut}>Log out</button>
10
) : (
11
<button onClick={logIn}>Log in</button>
12
)}
13
{isAuthenticated && <h1>Hello {currentUser.firstName}</h1>}
14
</>
15
)
16
}
17
18
export default HomePage

The isAuthenticated property checks if there is an active user session. Clicking the “Log in” button opens a modal window allowing you to sign in with the authentication methods chosen when you set up the project in the Clerk dashboard.

Since Clerk React is installed, you can use the Clerk components instead:

1
import { SignInButton, UserButton } from '@clerk/clerk-react'
2
import { useAuth } from '@redwoodjs/auth'
3
4
const HomePage = () => {
5
const { currentUser, isAuthenticated } = useAuth()
6
7
return (
8
<>
9
{isAuthenticated ? (
10
<UserButton afterSignOutAllUrl={window.location.href} />
11
) : (
12
<SignInButton mode="modal" />
13
)}
14
{isAuthenticated && <h1>Hello {currentUser.firstName}</h1>}
15
</>
16
)
17
}
18
19
export default HomePage

Clerk makes it super easy to add in these authentication components. There are further options for customization available as well.

Next steps

© 2022 Clerk. All rights reserved.