As part of your onboarding flow, you may want to collect extra information from your user and use it to drive your application state. Let’s walk through a quick example using Next.js and TypeScript to show you how simple implementing an onboarding flow can be.
In this guide, you will learn how to:
- Add custom claims to your session token
- Configure your middleware to read session data
- Update with the user’s onboarding state
To see a working example, check out our sample demonstration app here.
The examples below have been pared down to the bare minimum to enable you to easily customize them to your needs, you can build them with the Clerk + Next Quickstart using @clerk/nextjs 4.29.5 and Next 14.0.4.
Let’s get started!
Session tokens are JWTs that are generated by Clerk on behalf of your instance, and contain claims that allow you to store data about a user’s session. With Clerk, when a session token exists for a user, it indicates that the user is authenticated, and the associated claims can be retrieved at any time. [Learn More]
First, navigate to Sessions in your Clerk Dashboard and click the ‘Edit’ button. In the modal that opens, there will be a window where you can augment your session token with custom claims.
In there, add the following and hit save:
If you haven’t already, we can make the public metadata type information accessible to our application by adding the following to
We have just added custom data to our session token in the Clerk Dashboard and made those claims accessible to our app. Next, we’ll use
clerkMiddleware to redirect the user based on
authMiddleware() allows you ton configure access to your routes with fine grained control. You can also retrieve claims directly from the session and redirect your user accordingly. [Learn More]
Add the code sample below to your
Next, create a
layout.tsx file in
src/app/onboarding and add the following code to the file. This logic could go in the Middleware, but by adding to the
layout.tsx to the route the logic remains in one place. This file can also be expanded to handle multiple steps, if multiple steps are required for an onboarding flow.
Now that we have the logic for where to direct the user, we’ll need a way to track their onboarding status and note it on their session, let’s dig into that now!
Updating a user's
publicMetadata as they progress through the flow will allow us to recognize when they have successfully completed their onboarding and, per the logic above, are now able to access the application. [Learn More]
To do this you need:
- A method in your backend to securely update the user
- A process in your frontend with logic to collect and submit all the information for onboarding. In this guide you’ll use an example form.
First, add a method in your backend, that will be called on form submission and update the user’s
publicMetadata accordingly. The example below uses the
clerkClient wrapper to interact with the Backend API.
src/app/onboarding/_actions.ts add the following code snippet:
Now that we have a method to securely update our user’s
publicMetadata we can call this server action from a client side form.
With the backend updateUser method in place, we’ll add a basic page that contains a form to complete the onboarding process.
This example form that will capture an application name (applicationName) and application type of either B2C or B2B (applicationType). This is a very loose example — you can use this step to capture information from the user, sync user data to your database, have the user sign up to a course or subscription, or more.
To implement this logic, insert the following into your
Your onboarding flow is now complete! 🎉 New users who haven’t yet onboarded will now land on your
/onboarding page and, once they have completed onboarding, will be sent through to the dashboard. By using Clerk, which already handles user authentication, we were able to simplify the process of creating a custom user onboarding flow as well.