User Onboarding

Sometimes, you may want to collect additional information from users during sign-up, for example a real name or address. The most straightforward approach is to redirect users to an onboarding page right after they sign up. However, this is not recommended for the following reasons:

Users can accidentally (or purposefully) close or navigate away from the page before completing the onboarding.
Redirect URLs may vary depending on the context. For instance, if a user is redirected to a sign-in page after trying to access a protected page, they’ll expect to return to the original protected page post-authentication.

Instead, a more reliable strategy is to store an onboarded flag in the user’s metadata and redirect users to the onboarding page if they haven’t completed it yet.

Example implementation

Let’s say you have an onboarding page that asks for an address and stores it in the user’s metadata:

export default function OnboardingPage() {
  const user = useUser();
  const router = useRouter();
  const [address, setAddress] = useState('');

  return <>
    <input 
      type="text" 
      value={address} 
      onChange={(e) => setAddress(e.target.value)} 
    />

    <button onClick={async () => {
      await user.update({
        clientMetadata: {
          onboarded: true,
          address,
        },
      });
      router.push('/');
    }}>
      Submit
    </button>
    </>
  );
}

While the above implementation offers a basic onboarding process, users can still skip onboarding by directly sending an API request to update the clientMetadata.onboarded flag. If you want to ensure that onboarding cannot be bypassed on the API level, you should create a server endpoint to validate and store the data, then save the onboarded flag in the clientReadOnlyMetadata on the server side after validation.

Next, we can create a hook/function to check if the user has completed onboarding and redirect them to the onboarding page:

Client Component
Server Component

'use client';
import { useEffect } from 'react';
import { useUser } from '@hexclave/next';  // replace `next` with the correct framework SDK package
import { useRouter } from 'next/navigation';

export function useOnboarding() {
  const user = useUser();
  const router = useRouter();

  useEffect(() => {
    if (!user.clientReadOnlyMetadata.onboarded) {
      router.push('/onboarding');
    }
  }, [user]);
}

import { hexclaveServerApp } from '@/stack/server';
import { redirect } from 'next/navigation';

export async function ensureOnboarded() {
  const user = await hexclaveServerApp.getUser();
  if (!user.clientReadOnlyMetadata.onboarded) {
    redirect('/onboarding');
  }
}

You can then use these functions wherever onboarding is required:

Client Component
Server Component

import { useOnboarding } from '@/app/onboarding-hooks';
import { useUser } from '@hexclave/next';  // replace `next` with the correct framework SDK package

export default function HomePage() {
  useOnboarding();
  const user = useUser();

  return (
    <div>Welcome to the app, {user.displayName}</div>
  );
}

import { ensureOnboarding } from '@/app/onboarding-functions';
import { hexclaveServerApp } from '@/stack/server';

export default async function HomePage() {
  await ensureOnboarding();
  const user = await hexclaveServerApp.getUser();

  return (
    <div>Welcome to the app, {user.displayName}</div>
  );
}

Getting Started

Going Further

Apps

Integrations

Other

Example implementation

​Example implementation

Example implementation