ReCaptcha Module

Purpose

This module integrates Google reCAPTCHA into Adobe Commerce storefronts. It supports both reCAPTCHA v3 and reCAPTCHA Enterprise, providing methods for configuring, initializing, and verifying reCAPTCHA on protected forms.

The module queries the recaptchaFormConfig GraphQL endpoint to fetch per-form configuration, automatically detecting which reCAPTCHA type (v3 or Enterprise) is configured and loading the appropriate script.

Installation

npm i @adobe-commerce/recaptcha

Quick Start

import { setEndpoint, setConfig, initReCaptcha, verifyReCaptcha, enableLogger } from '@adobe-commerce/recaptcha';

// 1. Set the backend GraphQL endpoint
setEndpoint('https://your-store.com/graphql');

// 2. Fetch and store reCAPTCHA configuration
await setConfig([{ badgeId: 'generateCustomerToken' }]);

// 3. Initialize reCAPTCHA (loads script, renders badges)
initReCaptcha();

// 4. Get a token when submitting a protected form
const token = await verifyReCaptcha();

Public Methods

setEndpoint(url: string)

Sets the GraphQL endpoint URL used to fetch reCAPTCHA configuration.

setConfig(configList: PropsFormTypes[])

Fetches reCAPTCHA configuration from the backend via recaptchaFormConfig and stores it in session storage.

• Queries all known form types and determines which are enabled
• Normalizes the response into a unified config shape
• Detects the reCAPTCHA type (v3 or Enterprise) from the re_captcha_type field
• Skips forms with empty website_key
• Warns and disables reCAPTCHA if mixed types (both v3 and Enterprise) are detected across forms

await setConfig([
  { badgeId: 'generateCustomerToken' },
  { badgeId: 'contactUs' },
]);

initReCaptcha(lazyLoadTimeout?: number)

Initializes reCAPTCHA by loading the appropriate Google script and rendering badges.

• Loads enterprise.js for Enterprise or api.js for v3
• For inline badge position, renders invisible widgets into DOM elements matching each form's badgeId
• Default lazy load timeout: 3000ms

verifyReCaptcha(): Promise<string | undefined>

Generates and returns a reCAPTCHA token for form submission.

• Uses grecaptcha.enterprise.execute() for Enterprise or grecaptcha.execute() for v3
• Returns undefined if reCAPTCHA is not enabled or not configured

enableLogger(enabled: boolean)

Enables or disables debug logging. When enabled, logs are prefixed with [ReCaptcha] and include:

• Config fetch and normalization details
• Which reCAPTCHA type is detected and which forms are enabled
• Script loading URLs
• Badge rendering activity
• Token generation attempts
• Warnings for skipped forms (missing keys) or mixed type configurations

Supported Form Types

The module queries these form types from the backend:

| Form Type | Badge ID | |---|---| | PLACE_ORDER | placeOrder | | CONTACT | contactUs | | CUSTOMER_LOGIN | generateCustomerToken | | CUSTOMER_FORGOT_PASSWORD | requestPasswordResetEmail | | CUSTOMER_CREATE | createCustomerV2 | | CUSTOMER_EDIT | updateCustomerV2 | | NEWSLETTER | subscribeEmailToNewsletter | | PRODUCT_REVIEW | createProductReview | | SENDFRIEND | SENDFRIEND | | BRAINTREE | BRAINTREE |

Mixed Type Configuration

If the Commerce Admin has some forms configured with reCAPTCHA v3 and others with Enterprise, the module will:

1. Log a warning with instructions to update the Commerce Admin configuration
2. Disable reCAPTCHA entirely (returns no config, no script loaded)

All forms must use the same reCAPTCHA type. Configure this in the Commerce Admin under Stores > Configuration > Security > Google reCAPTCHA Storefront.