feat(clerk-react,nextjs,shared): Introduce experimental `useReverification`

[panteliselef]

Description

Introduce a new experimental hook called useReverification that makes it easy to handle reverification errors. It returns a high order function (HOF) and allows developers to wrap any function that triggers a fetch request which might fail due to a user's session verification status.

• When such error is returned, the recommended UX is to offer a way to the user to recover by re-verifying their credentials.
• This helper will automatically handle this flow in the developer's behalf, by displaying a modal the end-user can interact with.
• Upon completion, the original request that previously failed, will be retried (only once).

Video of UX flow

https://github.com/user-attachments/assets/e2071442-131e-4ea9-881d-ac4971ffd565

Nextjs example

A client component

import { __experimental_useReverification as useReverification } from "@clerk/nextjs";

export const DeletePatientButton = ({ name }: { name: string }) => {
  const { handleReverification } = useReverification();

  const [, trigger, isPending] = useActionState(
    handleReverification(deletePatientAction),
    {
      sucess: false,
    }
  );

  return (
    <button
      disabled={isPending}
      onClick={async () => {
        startTransition(() => {
          trigger(name);
        });
      }}
    >
      <LoadingChildren pending={isPending} />
    </button>
  );
};

function LoadingChildren({ pending }: { pending: boolean }) {
  if (pending) {
    return (
      <>
        Please wait
      </>
    );
  }

  return <>Delete</>;
}

our server actions

"use server";

import { removePatient } from "@/lib/db/patients";
import { auth } from "@clerk/nextjs/server";
import { reverificationMismatch } from "@clerk/shared/authorization-errors";

export const deletePatientAction = async (
  prevState: { sucess: boolean },
  name: string
) => {
  const { orgId } = await auth.protect();
  const { has } = await auth();
  if (
    !has({
      __experimental_reverification: "strict",
    })
  ) {
    return reverificationMismatch("strict");
  }

  removePatient(name, orgId);
  return { sucess: true };
};

Checklist

• [ ] npm test runs as expected.
• [ ] npm run build runs as expected.
• [ ] (If applicable) JSDoc comments have been added or updated for any package exports
• [ ] (If applicable) Documentation has been updated

Type of change

• [ ] 🐛 Bug fix
• [ ] 🌟 New feature
• [ ] 🔨 Breaking change
• [ ] 📖 Refactoring / dependency upgrade / documentation
• [ ] other:

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: f86c9cb2be9004ccdb866fe51770967813cf9d1a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
@clerk/nextjs	Minor
@clerk/clerk-react	Minor
@clerk/shared	Minor
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/elements	Patch
@clerk/clerk-expo	Patch
@clerk/remix	Patch
@clerk/tanstack-start	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/clerk-sdk-node	Patch
@clerk/testing	Patch
@clerk/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR