better-auth-captcha

The client half of better-auth's captcha plugin. It solves the captcha in the background and attaches the token to protected requests, so your forms don't change.

Install

npm install better-auth-captcha

ESM only. Requires better-auth 1.7+.

Usage

Server, using better-auth's own plugin:

import { betterAuth } from "better-auth";
import { captcha } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    captcha({
      provider: "cloudflare-turnstile",
      secretKey: env.TURNSTILE_SECRET_KEY,
    }),
  ],
});

Client:

import { createAuthClient } from "better-auth/react";
import { captchaClient } from "better-auth-captcha";
import { turnstile } from "better-auth-captcha/turnstile";

export const authClient = createAuthClient({
  plugins: [
    captchaClient({
      provider: turnstile({ siteKey: env.TURNSTILE_SITE_KEY }),
    }),
  ],
});

By default, the first protected request waits for the captcha to solve. To have a token ready before the user submits, call preload() on pages with a protected form:

authClient.captcha.preload();

It does nothing on the server, and calling it more than once is fine.

Providers

Each provider has setup steps of its own, so read its page before you ship.

| Provider | Server provider | Client import | | --------------------------------------------------- | ------------------------ | -------------------------------- | | Cloudflare Turnstile | "cloudflare-turnstile" | better-auth-captcha/turnstile | | Google reCAPTCHA v3 | "google-recaptcha" | better-auth-captcha/recaptcha | | hCaptcha | "hcaptcha" | better-auth-captcha/hcaptcha | | CaptchaFox | "captchafox" | better-auth-captcha/captchafox |

better-auth's Vercel BotID provider doesn't use a token, so use Vercel's botid client for it instead.

Options

| Option | Default | Description | | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------ | | provider | required | Where tokens come from, e.g. turnstile({ siteKey }). | | endpoints | ["/sign-up/email", "/sign-in/email", "/request-password-reset"] | Paths that get a token. Match the server plugin. |

License

MIT