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[], options?: { b2bEnabled?: boolean })

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

• Queries all default form types and determines which are enabled
• When options.b2bEnabled is true, includes COMPANY_CREATE in the query — this form type is not included by default
• 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

// B2C storefront (default)
await setConfig([{ badgeId: 'generateCustomerToken' }]);

// B2B storefront
await setConfig([], { b2bEnabled: true });

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

Default Form Types

These form types are queried by default (no additional configuration needed):

B2B Form Types

B2B storefronts should pass { b2bEnabled: true } to include COMPANY_CREATE in the reCAPTCHA query:

await setConfig([], { b2bEnabled: true });

This requires the backend to expose COMPANY_CREATE in ReCaptchaFormEnum.

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.