Invisible ReCAPTCHA with Next.js and TypeScript (deferred script)

As with most Google things, implementing a simple ReCAPTCHA comes with challenges:

Google's documentation is all over the place
Google's scripts always seem to hurt page speed scores (ironic)

Here's one of my sites using the default "out of the box" Captcha config:

In this post, we're going to talk about how we can fix this and implement an invisible captcha for your email signup forms that has a decent UX and is still performant.

CAPTCHA validation flow

The flow is pretty straightforward:

Generate a "token" client-side using Google's reCAPTCHA library and the public key
Pass the token to the backend (e.g. /api/subscribe)
Validate the generated token (that lasts 2 minutes) with the private key
If successful validation, add your user's email to mailing list (or other data source). If failure, handle error however you need to.

Get Captcha API Keys

Using the Google Recaptcha Admin Dashboard, create a new site.

For this tutorial, I'm using reCAPTCHA v2 with the "Invisible reCAPTCHA badge" setting.

Once you've got your keys, throw them in your .env.local file:

NEXT_PUBLIC_RECAPTCHA=<key>
RECAPTCHA_SECRET=<secret>

Write backend reCAPTCHA validator

Since we're dealing with Next.js, you can create an API route called /api/subscribe, which will accept the following body. I'm using Zod for validation here.

Note, the endpoint that I'm hitting, https://www.google.com/recaptcha/api/siteverify, is documented in Google's reCAPTCHA docs, but is very hidden.

import type { NextApiRequest, NextApiResponse } from "next";
import { z } from "zod";

type Response = {
  status: string;
  error?: string;
};

const Input = z.object({
  email: z.string().email(),
  captcha: z.string(),
});

const verifyEndpoint = "https://www.google.com/recaptcha/api/siteverify";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  if (req.method === "POST") {
    // Validate request
    const data = Input.parse(req.body);
    const { email, captcha } = data;

    // Validate a "token" that the client-side reCAPTCHA script generated for the user
    const captchaResponse = await fetch(verifyEndpoint, {
      method: "POST",
      headers: { "Content-type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        secret: process.env.RECAPTCHA_SECRET, // See prior section
        response: captcha, // the user's generated "Captcha" token
      }),
    }).then((res) => res.json());

    // If the verification fails, return 500x code
    if (!captchaResponse.success) {
      return res
        .status(500)
        .json({ status: "error", error: captchaResponse["error-codes"][0] });
    }

    // If verification succeeds, create a contact with your email provider
    // (this is just a mock)
    await myEmailProvider.addContact(email);

    res.status(200).json({ status: "ok" });
  } else {
    res.status(404); // Unhandled HTTP request
  }
}

Generate a reCAPTCHA token client-side

With our endpoint setup, we can create a barebones form to capture an email and run an "invisible" reCAPTCHA challenge. I'm using React Hook Form here as it's my go-to form library.

Install deps:

yarn add react-hook-form react-google-recaptcha

Finally, here is the EmailForm.tsx component:

import { useRef, useState } from "react";
import { useForm } from "react-hook-form";

import Captcha from "react-google-recaptcha";

export default function EmailForm() {
  const captchaRef = useRef<Captcha>(null);

  const { register, handleSubmit } = useForm({
    defaultValues: { email: "", captcha: "" },
  });

  return (
    <form
      onSubmit={handleSubmit(async (data) => {
        // Get the token
        const captcha = await captchaRef.current?.executeAsync();

        // Pass to Next.js API Route
        const res = await fetch("/api/subscribe", {
          method: "POST",
          body: JSON.stringify({ email: data.email, captcha }),
          headers: { "Content-type": "application/json" },
        });
      })}
    >
      <Captcha
        ref={captchaRef}
        size="invisible"
        sitekey={process.env.NEXT_PUBLIC_CAPTCHA!}
      />

      <label htmlFor="email-address" className="sr-only">
        Email address
      </label>
      <input
        type="email"
        autoComplete="email"
        placeholder="Enter your email"
        {...register("email", {
          required: true,
          pattern: {
            value: /\S+@\S+\.\S+/,
            message: "Entered value does not match email format",
          },
        })}
      />

      <button type="submit">Subscribe</button>
    </form>
  );
}

This works fine, but you're going to end up with Google's CAPTCHA script loading wherever this component is imported, which is likely going to be every page (if you throw this in a <footer /> or something similar).

We can improve page speed scores by deferring the initialization of the script until the user starts typing in the email field.

Optimize the reCAPTCHA script

Here is the same component, but with "lazy loading" of the script:

import { useRef, useState } from "react";
import { useForm } from "react-hook-form";

import Captcha from "react-google-recaptcha";

export default function EmailForm() {
  const captchaRef = useRef<Captcha>(null);

  const [captchaEnabled, setCaptchaEnabled] = useState(false);

  const { register, handleSubmit } = useForm({
    defaultValues: { email: "", captcha: "" },
  });

  // Watch for changes to email value and enable the CAPTCHA script
  const [email] = watch(["email"]);

  // Does this pattern look weird to you? See - https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes
  if (email && !captchaEnabled) {
    setCaptchaEnabled(true);
  }

  return (
    <form
      onSubmit={handleSubmit(async (data) => {
        // Get the token
        const captcha = await captchaRef.current?.executeAsync();

        // Pass to Next.js API Route
        const res = await fetch("/api/subscribe", {
          method: "POST",
          body: JSON.stringify({ email: data.email, captcha }),
          headers: { "Content-type": "application/json" },
        });
      })}
    >
      {/* Only enable CAPTCHA script if user has typed something */}
      {captchaEnabled && (
        <Captcha
          ref={captchaRef}
          size="invisible"
          sitekey={process.env.NEXT_PUBLIC_CAPTCHA!}
        />
      )}

      <label htmlFor="email-address" className="sr-only">
        Email address
      </label>
      <input
        type="email"
        autoComplete="email"
        placeholder="Enter your email"
        {...register("email", {
          required: true,
          pattern: {
            value: /\S+@\S+\.\S+/,
            message: "Entered value does not match email format",
          },
        })}
      />

      <button type="submit">Subscribe</button>
    </form>
  );
}