Next.js Payload FormBuilder reCAPTCHA v3 Demo

This repository demonstrates how to integrate Google reCAPTCHA v3 into a Next.js project using Payload CMS FormBuilder.
It includes both the client-side setup with react-google-recaptcha-v3 and the server-side verification logic.

Features

• reCAPTCHA v3 integration with Next.js
• Payload FormBuilder override for form validation
• Secure token verification on the server
• Configurable minimum score threshold
• Example provider and hook setup

Full Tutorial

For a detailed step-by-step explanation, read the full blog post:
How to use Google reCAPTCHA v3 with Next.js Payload v3 inside FormBuilder

Setup

1. Clone this repository:

git clone https://github.com/YOUR_GITHUB_USERNAME/nextjs-payload-recaptcha-demo
cd nextjs-payload-recaptcha-demo

2. Install dependencies:

pnpm install

3. Add the required environment variables in a .env file:

NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_site_key
RECAPTCHA_SECRET_KEY=your_secret_key
RECAPTCHA_MIN_SCORE=0.5

4. Run the development server:

pnpm dev

How it works

• The client uses react-google-recaptcha-v3 to request a token when a form is submitted.
• The token is sent to the server with the form data.
• The server validates the token against Google’s reCAPTCHA API.
• If the token is valid and the score is above your threshold, the form submission proceeds normally.

Structure

providers/
  ReCaptcha/
    index.ts          # Client-side provider

lib/
  verifyRecaptcha.ts  # Server-side verification

payload.config.ts     # FormBuilder hook integration

Testing

• Submit a form normally to confirm the request works.
• Try removing or altering the token to test error handling.
• Adjust RECAPTCHA_MIN_SCORE to test different trust thresholds.