Cloudflare Turnstile in Next.js

Stops automated form submissions. Free, no user puzzle in most cases, and pairs well with a form that already has validation + honeypot + rate limiting.

Env vars

NEXT_PUBLIC_TURNSTILE_SITE_KEY=   # public, safe in the client bundle
TURNSTILE_SECRET_KEY=             # server-only, never NEXT_PUBLIC

Design principle: graceful fallback. When the keys are absent the widget is not rendered and the server skips verification, so the form behaves exactly as before. It only enforces once both keys exist. This lets you ship the code first and turn it on later. (NEXT_PUBLIC_* bakes in at build → redeploy after setting.)

Client (inside a "use client" form component)

Use explicit rendering (not the implicit class="cf-turnstile" scan) — it is far more reliable in React. Guard against React's double-mount.

import Script from "next/script";
import { useEffect, useRef, useState } from "react";

const SITE_KEY = process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY;

interface TurnstileApi {
  render: (el: HTMLElement, o: { sitekey: string; theme?: "light" | "dark" | "auto";
    callback?: (t: string) => void; "error-callback"?: () => void; "expired-callback"?: () => void;
  }) => string;
  reset: (id?: string) => void;
  remove: (id?: string) => void;
}
declare global { interface Window { turnstile?: TurnstileApi } }

// inside the component:
const [scriptReady, setScriptReady] = useState(false);
const [token, setToken] = useState<string | null>(null);
const boxRef = useRef<HTMLDivElement>(null);
const idRef = useRef<string | null>(null);

useEffect(() => {
  if (!SITE_KEY || !scriptReady || !window.turnstile) return;
  if (!boxRef.current || idRef.current) return;          // guard: render once
  idRef.current = window.turnstile.render(boxRef.current, {
    sitekey: SITE_KEY, theme: "dark",
    callback: setToken,
    "expired-callback": () => setToken(null),
    "error-callback": () => setToken(null),
  });
  return () => { if (idRef.current) { window.turnstile?.remove(idRef.current); idRef.current = null; } };
}, [scriptReady]);

// on submit: block if (SITE_KEY && !token); include token in the payload;
// after the response, window.turnstile?.reset(idRef.current) + setToken(null) — tokens are single-use.

// in JSX (only when SITE_KEY is set):
// <Script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"
//   strategy="afterInteractive" onLoad={() => setScriptReady(true)} />
// <div ref={boxRef} />

Server (verify before doing any work)

async function verifyTurnstile(token: string | undefined, ip: string): Promise<boolean> {
  const secret = process.env.TURNSTILE_SECRET_KEY;
  if (!secret) return true;      // not configured → skip (graceful)
  if (!token) return false;
  try {
    const res = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ secret, response: token, remoteip: ip }),
    });
    const data = (await res.json()) as { success?: boolean };
    return data.success === true;
  } catch { return false; }
}

// in the route, AFTER parsing/honeypot and BEFORE sending anything:
// if (!(await verifyTurnstile(body.turnstileToken, ip)))
//   return NextResponse.json({ error: "Verification failed." }, { status: 403 });

Accept turnstileToken: z.string().max(4096).optional() in your request schema.

Cloudflare + Vercel setup

1. Cloudflare dashboard → Turnstile → Add widget → name it, add your production hostname (e.g. example.com; localhost is allowed automatically), mode Managed. You get a Site Key (public) + Secret Key (private).
2. Vercel → project env: NEXT_PUBLIC_TURNSTILE_SITE_KEY (site key) and TURNSTILE_SECRET_KEY (secret key). Redeploy (site key is build-time).
3. Verify: widget appears; submitting without solving is blocked; server 403s an invalid token.

Gotchas

• Implicit render (class="cf-turnstile") is flaky in React SPAs — use explicit.
• React 18 strict mode double-mounts effects — the idRef guard prevents two widgets.
• Turnstile tokens are single-use — reset() after every submit attempt.
• TURNSTILE_SECRET_KEY must be server-only; never prefix it NEXT_PUBLIC_.