--- title: "Goodbye reCAPTCHA, Hello Turnstile: Why I Switched (Next.js Guide)" author: "Rantideb Howlader" date: "2026-01-30T00:00:00.000Z" canonical_url: "https://www.ranti.dev/blog/migrating-from-recaptcha-to-turnstile" license: "CC-BY-4.0" --- If you've filled out a form on the internet in the last decade, you know the drill: "Select all squares with traffic lights." ![Turnstile vs reCAPTCHA](/blog/turnstile-migration-hero.webp) For years, [Google reCAPTCHA](https://developers.google.com/recaptcha/docs/display) has been the industry standard for preventing bot spam. But as the web evolves, the cracks are showing. On mobile devices, the "compact" widget frequently overflows containers. The constant challenge-response friction frustrates users. And for privacy-conscious developers, piping every visitor's interaction data through Google isn't ideal. This week, I migrated my entire portfolio - comments, contact forms, and "Ask Me Anything" widgets - from reCAPTCHA v2 to [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/). The result? **Zero friction.** My users are verified practically instantly, without clicking traffic lights. My mobile layout is fixed. And I eliminated a heavy dependency chain from my bundle. I'll walk you through exactly how to implement Turnstile in a **Next.js 14+** application, including a custom CSS trick for mobile responsiveness that most documentation misses. ## Why Turnstile? The "Smart" Alternative Before we write code, we need to justify the engineering effort. Why fix what works? ### 1. The Mobile UX Problem This was my primary trigger. On my portfolio, the standard reCAPTCHA widget (`width: 304px`) would constantly break layout on small screens (iPhone SE, Galaxy Fold). The "compact" mode exists, but it looks outdated and often fails to renders correctly in dark mode. ### 2. Privacy-First Verification: The Magic of PATs Cloudflare Turnstile is built on a privacy-first architecture, but what does that actually mean? It leverages standard browser APIs and **Private Access Tokens (PATs)** on supported devices (iOS 16+, macOS Ventura+). Think of a PAT as a digital "VIP wristband." Your device (Apple) tells the website (Cloudflare), "Hey, I can vouch for this user. They unlocked their phone with FaceID, they prefer privacy, and they aren't a script." Cloudflare accepts this distinct cryptographic token without ever needing to know whom the user is, tracking their history, or setting a persistent cookie. **Google reCAPTCHA**, by contrast, often relies on analyzing a user's history across the web (using Google cookies) to determine if they are "human enough." If you browse in Incognito mode or block third-party cookies, reCAPTCHA assumes you might be a bot and punishes you with endless "Select the Fire Hydrant" puzzles. Turnstile doesn't punish privacy; it rewards it. ### 3. Performance & Core Web Vitals As a frontend engineer, I care deeply about **TBT (Total Blocking Time)** and **LCP (Largest Contentful Paint)**. Google's reCAPTCHA script is notoriously heavy. It loads multiple external resources, executes significant main-thread JavaScript to track mouse movements and entropy, and often forces layout shifts when the badge loads. **The Impact on my PageSpeed:** - **reCAPTCHA:** ~200ms TBT cost, often flagged as "Reduce unused JavaScript." - **Turnstile:** ~40ms TBT cost. The script is significantly smaller and lazily executes challenges only when needed. By switching, I shaved roughly 150ms off my TBT - a massive win for a simple form component. ### 4. Accessibility (a11y) Have you ever tried to solve a reCAPTCHA image puzzle using a screen reader? It's a nightmare. The "audio challenge" fallback is often garbled or incredibly difficult to parse for non-native speakers. Turnstile's "Managed" mode is a game-changer for accessibility. Because it validates the request and browser environment rather than the user's ability to see/hear/click, most users with disabilities effectively skip the challenge entirely. They simply press "Submit," and it works. ### Comparison: reCAPTCHA vs. Turnstile | Feature | Google reCAPTCHA v2 | Cloudflare Turnstile | | :---------------------- | :--------------------------------- | :----------------------------- | | **User Experience** | High Friction (Traffic lights) | Low Friction (Invisible/Smart) | | **Mobile UX** | Poor (Fixed width overflows) | Excellent (Responsive) | | **Verification Method** | User Behavior Tracking (Cookies) | Environment/PATs (Privacy) | | **Privacy** | Data piped to Google Ads ecosystem | No data selling/retention | | **Performance (TBT)** | Heavy (~200ms impact) | Lightweight (~40ms impact) | | **Accessibility** | Difficult (Visual puzzles) | Excellent (Passive) | | **Cost** | Free up to 1M (then Enterprise) | Free (Unlimited for Managed) | ## Prerequisites Before identifying as a human, you need keys. 1. Go to the [Cloudflare Dashboard](https://dash.cloudflare.com/) -> **Turnstile**. 2. Click **Add Site**. 3. **Site Name**: `Your Project Name`. 4. **Domain**: Add your production domain (`ranti.dev`) AND `localhost`. 5. **Widget Mode**: Choose **Managed** (Recommended). This lets Cloudflare decide when to show a challenge vs. just automatically passing the user. 6. Grab your **Site Key** and **Secret Key**. **Important:** Do not opt-in to "Pre-Clearance" unless your site is proxied behind Cloudflare. For Vercel/Netlify deployments, leave this off. ## Step 1: Frontend Implementation We'll use the official react wrapper: `@marsidev/react-turnstile`. It's a lightweight wrapper that handles the script loading cleanly, avoiding the `react-async-script` dependency hell that `react-google-recaptcha` brings. ### Install the Package ```bash pnpm add @marsidev/react-turnstile # or npm install @marsidev/react-turnstile ``` ### The Component Here is a robust implementation that handles **Dark Mode automated detection** and **Validation State**. ```tsx "use client"; import { useState } from "react"; import { Turnstile } from "@marsidev/react-turnstile"; export default function SecureForm() { const [token, setToken] = useState(null); return (
{/* ... other fields ... */}
setToken(token)} onError={() => setToken(null)} onExpire={() => setToken(null)} options={{ theme: "auto", // Automatically respects system preference size: "flexible", // Attempts to resize (see Mobile Tip below) }} />
); } ``` ## Step 2: The "Secret Sauce" (Mobile Fix) 📱 Here is the part most tutorials skip. Even with `size="flexible"`, the Turnstile widget can be stubborn on very small viewports (under 320px). It might cause horizontal scrolling which fails Core Web Vitals **CLS** (Cumulative Layout Shift) checks. To fix this, I wrapped the widget in a scaling container. This forces the widget to fit regardless of the viewport width. ```tsx // Inside your JSX
``` **Why this works:** - **`origin-left`**: Keeps the widget aligned to the start of your form. - **`scale-[0.85]`**: On mobile, it shrinks the widget just enough (to approx 255px) to fit comfortably in any standard padding container. - **`sm:scale-100`**: On tablet/desktop, it returns to natural size. This simple trick saved my layout Score on PageSpeed Insights. ## Step 3: Backend Verification (Next.js API) Sending the token is half the battle. You must verify it on the server. **File:** `app/api/verify/route.ts` ```typescript import { NextResponse } from "next/server"; const SECRET_KEY = process.env.TURNSTILE_SECRET_KEY; export async function POST(request: Request) { const { token } = await request.json(); const ip = request.headers.get("x-forwarded-for"); // Call Cloudflare's verification endpoint const formData = new FormData(); formData.append("secret", SECRET_KEY!); formData.append("response", token); formData.append("remoteip", ip || ""); const result = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { body: formData, method: "POST", }); const outcome = await result.json(); if (!outcome.success) { return NextResponse.json({ error: "Invalid Captcha" }, { status: 400 }); } return NextResponse.json({ success: true }); } ``` **Note: Always pass the `remoteip` if possible. It helps Turnstile's risk engine make smarter decisions about handling the request.** ## Step 4: Content Security Policy (CSP) 🛡️ If you run a strict CSP (and you should), Turnstile will break immediately because it loads scripts from `challenges.cloudflare.com`. You need to update your `middleware.ts` or CSP headers config. **Directives to update:** | Directive | Value to Add | | :---------------- | :---------------------------------- | | **`script-src`** | `https://challenges.cloudflare.com` | | **`frame-src`** | `https://challenges.cloudflare.com` | | **`connect-src`** | `https://challenges.cloudflare.com` | Failure to add `connect-src` will result in a confusing error where the widget renders but fails to ever reach "Success" state. ### 5. The Trade-off: Centralization To be balanced, we must acknowledge the trade-off. By switching from Google to Cloudflare, we are technically trading one giant for another. While Cloudflare's privacy stance is currently more favorable for the open web than an ad-tech company's, you are still relying on a centralized service. If Cloudflare has an outage, your forms could theoretically be impacted (though their uptime is stellar). For 100% independence, you would need a self-hosted PoW solution, but those rarely match the bot-detection accuracy and speed of a global network like Turnstile. ## Final Thoughts & Live Demo Migrating to Turnstile wasn't just a technical task; it was a user experience upgrade. By removing friction, I've noticed an uptick in engagement on my "Ask Me Anything" feature. Users are verified faster, and I sleep better knowing I'm using a privacy-preserving solution. **Want to see it in action?** Don't just take my word for it. Scroll down to the **comment section below** and post a test comment. See how fast that checkmark appears? That's the Turnstile difference. 👇 ## FAQ ### Is Cloudflare Turnstile free? Yes, Cloudflare Turnstile provides unlimited free usage for its 'Managed' mode. Unlike reCAPTCHA Enterprise which imposes usage limits and billing after 1 million checks, Turnstile remains free for most standard use cases. ### Does Turnstile block real users? Turnstile is designed to be low-friction. In Managed mode, it rarely shows a manual puzzle. It uses browser environment analysis to distinguish bots from humans, so legitimate users usually pass instantly without clicking anything. ### Can I use Turnstile with Vercel? Absolutely. Turnstile is platform-agnostic. It works perfectly on Vercel, Netlify, AWS, or any other hosting provider. You just need to add the correct environment variables (`NEXT_PUBLIC_TURNSTILE_SITE_KEY` and `TURNSTILE_SECRET_KEY`) to your deployment settings. ### Is Cloudflare Turnstile GDPR compliant? Cloudflare Turnstile is 'privacy-first' and does not look for unique cookies (like Google login cookies) to verify users. Cloudflare states they do not use Turnstile data for advertising purposes. However, as with any third-party script, you should update your Privacy Policy to disclose its usage. ### Does it support dark mode? Yes, the widget supports `theme: "auto"`, `theme: "light"`, and `theme: "dark"`. In "auto" mode, it respects the user's system preference or the `prefers-color-scheme` media query, making it seamless for dark-themed sites. ### What happens if JavaScript is disabled? Like reCAPTCHA, Cloudflare Turnstile requires JavaScript to function. If a user has strictly disabled JavaScript, they will not be able to pass the verification. It is best practice to include a `