Recaptcha Integration

reCAPTCHA Enterprise integration

Reuse the bundled implementation and adapt only paths, aliases, router wiring, and existing project conventions. Keep the result small: one action/payload type, one error class and guard, one browser helper, one server validator, one script component, and one public constant.

Workflow

1. Inspect the target project's Next.js router, source layout, aliases, package manager, environment files, public-environment-variable modules, global styles and override stylesheets, API error handling, and any existing reCAPTCHA code.
2. Read references/manual-prerequisites.md for the Google Cloud, service-account, and environment handoff. Copy the bundled scripts/encode-recaptcha-key.js unchanged to the target project root. It encodes the downloaded JSON key's private_key; take project_id and client_email directly from that JSON.
3. Read references/integration-workflow.md for client, server, route, and error-handler wiring.
4. Read references/template-catalog.md before using the bundled files.
5. Check current Google Cloud reCAPTCHA and Next.js documentation through Context7 before implementation.

Actions and score

• Use actions requested by the user. Otherwise infer them from the operations being protected when unambiguous; ask when the choice affects product behavior.
• For a generic integration with no stated action, use CONTACT = "contact".
• Use 0.6 as the default minimum score. If the user chooses another score, use that value instead.
• Keep action values stable and low-cardinality, for example contact, login, register, or checkout.
• Send the action with the token in RecaptchaPayload. Each server route must validate that the submitted action is the one approved for that operation before passing the payload to the server validator.

Reuse the scaffold

For the default src layout, preview and then run:

python <skill-directory>/scripts/scaffold_recaptcha.py \
  --project-root <project-root> \
  --actions contact login \
  --score 0.6 \
  --dry-run

Remove --dry-run after reviewing the destinations. The script refuses to overwrite files; when related files exist, update them manually instead of replacing them wholesale.

If the project uses different paths, copy the matching files from assets/templates/nextjs-typescript/ and adapt imports. Preserve the implementation shape rather than adding extra abstractions.

Public site-key placement

Search for the project's established module for NEXT_PUBLIC_* variables. Add RECAPTCHA_SITE_KEY there and preserve its naming, validation, and export conventions. If no shared public-variable module exists, use the scaffold's src/constants/recaptcha.ts fallback. Do not keep both.

Badge styling

Hide the Google badge:

/* Hide reCAPTCHA badge */
.grecaptcha-badge {
  visibility: hidden;
}

Use the project's existing browser/vendor override stylesheet and confirm that its global stylesheet imports it once. If none exists, create overrides.css beside the global stylesheet, put the rule there, and import it once from the global stylesheet. Do not put the rule directly in the global stylesheet or create a competing global-style entry point.

Critical corrections retained from the source implementation

The bundled version intentionally makes only these correctness and security improvements:

• wait for grecaptcha.enterprise.ready before executing;
• generate a fresh token immediately before each protected request;
• keep the request payload as the generated token plus the exact action used to generate it;
• validate the payload action against the route-approved action before assessment;
• pass the validated action as the assessment's expected action and compare Google's returned action;
• reject invalid tokens, missing/non-finite scores, and scores below the threshold, including score 0;
• cache the Google SDK client instead of creating it for every request;
• run reCAPTCHA validation before protected work;
• keep credentials and assessment code server-only.

Keep one ReCaptchaError class and one guard. Add more error or policy layers only when the target project already requires them.

Dependencies

Install compatible current versions with the project's package manager:

@google-cloud/recaptcha-enterprise
@types/grecaptcha (development dependency when TypeScript needs the global types)

Credential handoff

Before handoff, give the developer the console steps and command in references/manual-prerequisites.md.

Copy the bundled paste-and-run encoder byte-for-byte to the target project root as encode-recaptcha-key.js:

cp <skill-directory>/scripts/encode-recaptcha-key.js <project-root>/encode-recaptcha-key.js

The developer pastes the downloaded JSON key's private_key value into the script, runs node encode-recaptcha-key.js, and copies the base64 output into RECAPTCHA_PRIVATE_KEY. Never change the bundled encoder's contents. Do not commit a pasted private key.

Finish

Run the project's formatter, linter, type checker, and relevant tests. Report:

• files created or changed;
• protected actions and score;
• manual Google Cloud and environment steps;
• verification results;
• any project-specific adaptation still required.