# Recaptcha Integration

> Add, migrate, or review score-based Google Cloud reCAPTCHA Enterprise in TypeScript Next.js applications. Use this skill when protecting forms, API routes, route handlers, or server actions; configuring reCAPTCHA actions, score thresholds, environment variables, browser token generation, or server assessments; or reusing the bundled project-standard scaffold. Do not use it for unrelated checkbox or image CAPTCHA implementations.

- Skill: `ilya-valasiuk/recaptcha-integration` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add ilya-valasiuk/recaptcha-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ilya-valasiuk/recaptcha-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ilya-valasiuk (https://skillmd.com/u/ilya-valasiuk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ilya-valasiuk/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](references/manual-prerequisites.md) for the Google Cloud, service-account, and environment handoff. Copy the bundled [`scripts/encode-recaptcha-key.js`](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](references/integration-workflow.md) for client, server, route, and error-handler wiring.
4. Read [references/template-catalog.md](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:

```bash
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:

```css
/* 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:

```text
@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](references/manual-prerequisites.md).

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

```bash
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.