next-recaptcha-v3 1.5.2 → 2.0.0-beta.1

package/README.md

@@ -18,18 +18,20 @@ Straightforward solution for using ReCaptcha in your [Next.js](https://nextjs.or
 ## Install
 
 ```ssh
-yarn add next-recaptcha-v3
+npm i next-recaptcha-v3
 ```
 
-or
+```ssh
+pnpm i next-recaptcha-v3
+```
 
 ```ssh
-npm install next-recaptcha-v3 --save
+yarn add next-recaptcha-v3
 ```
 
 ## Pure ESM package
 
-This package is now [pure ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). It cannot be `require()`'d from CommonJS.
+This package is [pure ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). It cannot be `require()`'d from CommonJS.
 
 ## Generate reCAPTCHA Key
 
@@ -85,9 +87,11 @@ const {
   reCaptchaKey,
   /** Global ReCaptcha object */
   grecaptcha,
-  /** Is ReCaptcha script loaded */
-  loaded,
-  /** Is ReCaptcha script failed to load */
+  /** If `true`, ReCaptcha script has been loaded */
+  isLoaded,
+  /** If `true`, an error occurred while loading ReCaptcha script */
+  isError,
+  /** Error received while loading ReCaptcha script */
   error,
   /** Other hook props */
   ...otherProps
@@ -195,18 +199,18 @@ import { validateToken } from "./utils";
 
 interface MyPageProps extends WithReCaptchaProps {}
 
-const MyPage: React.FC<MyPageProps> = ({ loaded, executeRecaptcha }) => {
+const MyPage: React.FC<MyPageProps> = ({ isLoaded, executeRecaptcha }) => {
   const [token, setToken] = useState<string>(null);
 
   useEffect(() => {
-    if (loaded) {
+    if (isLoaded) {
       const generateToken = async () => {
         const newToken = await executeRecaptcha("page_view");
         setToken(newToken);
       };
       generateToken();
     }
-  }, [loaded, executeRecaptcha]);
+  }, [isLoaded, executeRecaptcha]);
 
   useEffect(() => {
     if (token) {

package/lib/ReCaptcha.d.ts

@@ -1,4 +1,4 @@
-interface ReCaptchaProps {
+export interface ReCaptchaProps {
     onValidate: (token: string) => void;
     action: string;
     validate?: boolean;
@@ -8,6 +8,4 @@ interface ReCaptchaProps {
  * @example
  * <ReCaptcha action='form_submit' onValidate={handleToken} />
  */
-declare const ReCaptcha: React.FC<ReCaptchaProps>;
-export { ReCaptcha };
-export type { ReCaptchaProps };
+export declare const ReCaptcha: React.FC<ReCaptchaProps>;

package/lib/ReCaptcha.js

@@ -7,9 +7,9 @@ import { useReCaptcha } from './useReCaptcha.js';
  * <ReCaptcha action='form_submit' onValidate={handleToken} />
  */
 const ReCaptcha = ({ action, onValidate, validate = true, reCaptchaKey, }) => {
-    const { loaded, executeRecaptcha } = useReCaptcha(reCaptchaKey);
+    const { isLoaded, executeRecaptcha } = useReCaptcha(reCaptchaKey);
     useEffect(() => {
-        if (!validate || !loaded)
+        if (!validate || !isLoaded)
             return;
         if (typeof onValidate !== "function")
             return;
@@ -18,7 +18,7 @@ const ReCaptcha = ({ action, onValidate, validate = true, reCaptchaKey, }) => {
             onValidate(token);
         };
         handleExecuteRecaptcha();
-    }, [action, onValidate, validate, loaded, executeRecaptcha]);
+    }, [action, onValidate, validate, isLoaded, executeRecaptcha]);
     return null;
 };
 

package/lib/ReCaptchaProvider.d.ts

@@ -1,26 +1,32 @@
 import React from "react";
 import { ScriptProps } from "next/script.js";
-import type { IReCaptcha } from "./recaptcha.types.js";
-interface ReCaptchaContextProps {
+type ReCaptchaConfigProps = {
     /** reCAPTCHA_site_key */
     readonly reCaptchaKey: string | null;
-    /** Global ReCaptcha object */
-    readonly grecaptcha: IReCaptcha | null;
-    /** Is ReCaptcha script loaded */
-    readonly loaded: boolean;
-    /** Is ReCaptcha failed to load */
-    readonly error: boolean;
-}
-declare const ReCaptchaContext: React.Context<ReCaptchaContextProps>;
-declare const useReCaptchaContext: () => ReCaptchaContextProps;
-interface ReCaptchaProviderProps extends Partial<Omit<ScriptProps, "onLoad">> {
+    /** Language code */
+    readonly language: string | null;
+    /** Use ReCaptcha Enterprise */
+    readonly useEnterprise: boolean;
+    /** Whether to use recaptcha.net for loading the script */
+    readonly useRecaptchaNet: boolean;
+};
+type ReCaptchaStateProps = {
+    /** If `true`, ReCaptcha script has been loaded */
+    readonly isLoaded: boolean;
+    /** If `true`, an error occurred while loading ReCaptcha script */
+    readonly isError: boolean;
+    /** Error received while loading ReCaptcha script */
+    readonly error: Error | null;
+};
+export type ReCaptchaContextProps = ReCaptchaConfigProps & ReCaptchaStateProps;
+export declare const ReCaptchaContext: React.Context<ReCaptchaContextProps>;
+export declare const useReCaptchaContext: () => ReCaptchaContextProps;
+export interface ReCaptchaProviderProps extends Partial<ScriptProps> {
     reCaptchaKey?: string;
-    language?: string;
+    language?: string | null;
     useRecaptchaNet?: boolean;
     useEnterprise?: boolean;
     children?: React.ReactNode;
-    onLoad?: (grecaptcha: IReCaptcha, e: any) => void;
 }
-declare const ReCaptchaProvider: React.FC<ReCaptchaProviderProps>;
-export { ReCaptchaContext, useReCaptchaContext, ReCaptchaProvider };
-export type { ReCaptchaContextProps, ReCaptchaProviderProps };
+export declare const ReCaptchaProvider: React.FC<ReCaptchaProviderProps>;
+export {};

package/lib/ReCaptchaProvider.js

@@ -1,61 +1,51 @@
 "use client";
-import React, { createContext, useContext, useDebugValue, useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
 import Script from 'next/script.js';
-import { getRecaptchaScriptSrc } from './utils.js';
+import { RECAPTCHA_LOADED_EVENT, getRecaptchaScriptSrc } from './utils.js';
 
 const ReCaptchaContext = createContext({
     reCaptchaKey: null,
-    grecaptcha: null,
-    loaded: false,
-    error: false,
+    language: null,
+    useEnterprise: false,
+    useRecaptchaNet: false,
+    isLoaded: false,
+    isError: false,
+    error: null,
 });
-const useReCaptchaContext = () => {
-    const values = useContext(ReCaptchaContext);
-    useDebugValue(`grecaptcha available: ${values?.loaded ? "Yes" : "No"}`);
-    useDebugValue(`ReCaptcha Script: ${values?.loaded ? "Loaded" : "Not Loaded"}`);
-    useDebugValue(`Failed to load Script: ${values?.error ? "Yes" : "No"}`);
-    return values;
-};
-const ReCaptchaProvider = ({ reCaptchaKey: passedReCaptchaKey, useEnterprise = false, useRecaptchaNet = false, language, children, id = "google-recaptcha-v3", strategy = "afterInteractive", src: passedSrc, onLoad: passedOnLoad, onError: passedOnError, ...props }) => {
-    const [grecaptcha, setGreCaptcha] = useState(null);
-    const [loaded, setLoaded] = useState(false);
-    const [error, setError] = useState(false);
+const useReCaptchaContext = () => useContext(ReCaptchaContext);
+const ReCaptchaProvider = ({ reCaptchaKey: passedReCaptchaKey, useEnterprise = false, useRecaptchaNet = false, language = null, children, strategy = "afterInteractive", src: passedSrc, onReady: passedOnReady, onError: passedOnError, ...props }) => {
+    const [isLoaded, setIsLoaded] = useState(false);
+    const [error, setError] = useState(null);
+    const isError = !!error;
     const reCaptchaKey = passedReCaptchaKey || process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY || null;
     const src = passedSrc ||
         getRecaptchaScriptSrc({ reCaptchaKey, language, useRecaptchaNet, useEnterprise }) ||
         null;
-    // Reset state when script src is changed
-    const mounted = useRef(false);
-    useEffect(() => {
-        if (mounted.current) {
-            setLoaded(false);
-            setError(false);
-        }
-        mounted.current = true;
-    }, [src]);
     // Handle script load
-    const onLoad = useCallback((e) => {
-        const grecaptcha = useEnterprise ? window?.grecaptcha?.enterprise : window?.grecaptcha;
-        if (grecaptcha) {
-            grecaptcha.ready(() => {
-                setGreCaptcha(grecaptcha);
-                setLoaded(true);
-                passedOnLoad?.(grecaptcha, e);
-            });
-        }
-    }, [passedOnLoad, useEnterprise]);
-    // Run 'onLoad' function once just in case if grecaptcha is already globally available in window
-    useEffect(() => onLoad(), [onLoad]);
+    const onReady = useCallback(() => {
+        setError(null);
+        setIsLoaded(true);
+        window.dispatchEvent(new Event(RECAPTCHA_LOADED_EVENT));
+        passedOnReady?.();
+    }, [passedOnReady]);
     // Handle script error
     const onError = useCallback((e) => {
-        setError(true);
+        setError(e);
         passedOnError?.(e);
     }, [passedOnError]);
     // Prevent unnecessary rerenders
-    const value = useMemo(() => ({ reCaptchaKey, grecaptcha, loaded, error }), [reCaptchaKey, grecaptcha, loaded, error]);
+    const value = useMemo(() => ({
+        reCaptchaKey,
+        language,
+        useEnterprise,
+        useRecaptchaNet,
+        isLoaded: isLoaded,
+        isError,
+        error,
+    }), [reCaptchaKey, language, useEnterprise, useRecaptchaNet, isLoaded, isError, error]);
     return (React.createElement(ReCaptchaContext.Provider, { value: value },
         children,
-        React.createElement(Script, { id: id, src: src, strategy: strategy, onLoad: onLoad, onError: onError, ...props })));
+        React.createElement(Script, { src: src, strategy: strategy, onReady: onReady, onError: onError, ...props })));
 };
 
 export { ReCaptchaContext, ReCaptchaProvider, useReCaptchaContext };

package/lib/useReCaptcha.d.ts

@@ -1,10 +1,30 @@
 import type { ReCaptchaContextProps } from "./ReCaptchaProvider.js";
+import type { IReCaptcha } from "./recaptcha.types.js";
 export interface useReCaptchaProps extends ReCaptchaContextProps {
+    /** reCAPTCHA instance */
+    grecaptcha: IReCaptcha | null;
+    /**
+     * Executes the reCAPTCHA verification process for a given action.
+     * Actions may only contain alphanumeric characters and slashes, and must not be user-specific.
+     */
     executeRecaptcha: (action: string) => Promise<string>;
 }
-/** React Hook to generate ReCaptcha token
+/**
+ * Custom hook to use Google reCAPTCHA v3.
+ *
+ * @param [reCaptchaKey] - Optional reCAPTCHA site key. If not provided, it will use the key from the context.
+ * @returns An object containing the reCAPTCHA context, grecaptcha instance, reCaptchaKey, and executeRecaptcha function.
+ *
  * @example
- * const { executeRecaptcha } = useReCaptcha()
+ * const { executeRecaptcha } = useReCaptcha();
+ *
+ * const handleSubmit = async () => {
+ *   try {
+ *     const token = await executeRecaptcha('your_action');
+ *     // Use the token for verification
+ *   } catch (error) {
+ *     console.error('ReCAPTCHA error:', error);
+ *   }
+ * };
  */
-declare const useReCaptcha: (reCaptchaKey?: string) => useReCaptchaProps;
-export { useReCaptcha };
+export declare const useReCaptcha: (reCaptchaKey?: string) => useReCaptchaProps;

package/lib/useReCaptcha.js

@@ -1,31 +1,53 @@
 "use client";
-import { useRef, useCallback } from 'react';
+import { useCallback } from 'react';
 import { useReCaptchaContext } from './ReCaptchaProvider.js';
-import { useIsomorphicLayoutEffect } from './utils.js';
+import { useGrecaptcha, getGrecaptcha } from './utils.js';
 
-/** React Hook to generate ReCaptcha token
+/**
+ * Custom hook to use Google reCAPTCHA v3.
+ *
+ * @param [reCaptchaKey] - Optional reCAPTCHA site key. If not provided, it will use the key from the context.
+ * @returns An object containing the reCAPTCHA context, grecaptcha instance, reCaptchaKey, and executeRecaptcha function.
+ *
  * @example
- * const { executeRecaptcha } = useReCaptcha()
+ * const { executeRecaptcha } = useReCaptcha();
+ *
+ * const handleSubmit = async () => {
+ *   try {
+ *     const token = await executeRecaptcha('your_action');
+ *     // Use the token for verification
+ *   } catch (error) {
+ *     console.error('ReCAPTCHA error:', error);
+ *   }
+ * };
  */
 const useReCaptcha = (reCaptchaKey) => {
-    const { grecaptcha, loaded, reCaptchaKey: contextReCaptchaKey, ...contextProps } = useReCaptchaContext();
-    const siteKey = reCaptchaKey || contextReCaptchaKey;
-    // Create a ref that stores 'grecaptcha.execute' method to prevent rerenders
-    const executeCaptchaRef = useRef(grecaptcha?.execute);
-    useIsomorphicLayoutEffect(() => {
-        executeCaptchaRef.current = grecaptcha?.execute;
-    }, [loaded, grecaptcha?.execute]);
+    const context = useReCaptchaContext();
+    const { useEnterprise } = context;
+    const grecaptcha = useGrecaptcha(useEnterprise);
+    const siteKey = reCaptchaKey || context.reCaptchaKey;
     const executeRecaptcha = useCallback(async (action) => {
-        if (typeof executeCaptchaRef.current !== "function") {
-            throw new Error("Recaptcha has not been loaded");
-        }
         if (!siteKey) {
             throw new Error("ReCaptcha sitekey is not defined");
         }
-        const result = await executeCaptchaRef.current(siteKey, { action });
+        const grecaptcha = getGrecaptcha(useEnterprise);
+        if (typeof grecaptcha?.execute !== "function") {
+            throw new Error("Recaptcha has not been loaded");
+        }
+        if (typeof grecaptcha.ready === "function") {
+            await new Promise((resolve) => {
+                grecaptcha.ready(resolve);
+            });
+        }
+        const result = await grecaptcha.execute(siteKey, { action });
         return result;
-    }, [siteKey]);
-    return { ...contextProps, grecaptcha, loaded, reCaptchaKey: siteKey, executeRecaptcha };
+    }, [useEnterprise, siteKey]);
+    return {
+        ...context,
+        grecaptcha,
+        reCaptchaKey: siteKey,
+        executeRecaptcha,
+    };
 };
 
 export { useReCaptcha };

package/lib/utils.d.ts

@@ -1,4 +1,5 @@
-import { useLayoutEffect } from "react";
+import { IReCaptcha } from "./recaptcha.types.js";
+export declare const RECAPTCHA_LOADED_EVENT = "recaptcha_loaded";
 /**
  * Function to generate the src for the script tag
  * Refs: https://developers.google.com/recaptcha/docs/loading
@@ -9,4 +10,9 @@ export declare const getRecaptchaScriptSrc: ({ reCaptchaKey, language, useRecapt
     useRecaptchaNet?: boolean;
     useEnterprise?: boolean;
 }) => string;
-export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+export declare const getGrecaptcha: (useEnterprise?: boolean) => IReCaptcha | null;
+/**
+ * Hook to get the grecaptcha object
+ * @param useEnterprise - Use ReCaptcha Enterprise
+ */
+export declare const useGrecaptcha: (useEnterprise?: boolean) => IReCaptcha | null;

package/lib/utils.js

@@ -1,6 +1,7 @@
 "use client";
-import { useLayoutEffect, useEffect } from 'react';
+import { useSyncExternalStore } from 'react';
 
+const RECAPTCHA_LOADED_EVENT = "recaptcha_loaded";
 /**
  * Function to generate the src for the script tag
  * Refs: https://developers.google.com/recaptcha/docs/loading
@@ -15,7 +16,21 @@ const getRecaptchaScriptSrc = ({ reCaptchaKey, language, useRecaptchaNet = false
         src += `&hl=${language}`;
     return src;
 };
-// https://usehooks-ts.com/react-hook/use-isomorphic-layout-effect
-const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+const getGrecaptcha = (useEnterprise = false) => {
+    if (useEnterprise && window.grecaptcha?.enterprise)
+        return window.grecaptcha.enterprise;
+    return window.grecaptcha || null;
+};
+/**
+ * Hook to get the grecaptcha object
+ * @param useEnterprise - Use ReCaptcha Enterprise
+ */
+const useGrecaptcha = (useEnterprise = false) => {
+    const grecaptcha = useSyncExternalStore((callback) => {
+        window.addEventListener(RECAPTCHA_LOADED_EVENT, callback);
+        return () => window.removeEventListener(RECAPTCHA_LOADED_EVENT, callback);
+    }, () => getGrecaptcha(useEnterprise), () => null);
+    return grecaptcha;
+};
 
-export { getRecaptchaScriptSrc, useIsomorphicLayoutEffect };
+export { RECAPTCHA_LOADED_EVENT, getGrecaptcha, getRecaptchaScriptSrc, useGrecaptcha };

package/lib/withReCaptcha.d.ts

@@ -1,14 +1,11 @@
 import React from "react";
 import type { useReCaptchaProps } from "./useReCaptcha.js";
-interface WithReCaptchaProps extends useReCaptchaProps {
-}
+export type WithReCaptchaProps = useReCaptchaProps;
 /** React HOC to generate ReCaptcha token
  * @example
  * withReCaptcha(MyComponent)
  */
-declare function withReCaptcha<T extends WithReCaptchaProps = WithReCaptchaProps>(WrappedComponent: React.ComponentType<T>): {
+export declare function withReCaptcha<T extends WithReCaptchaProps = WithReCaptchaProps>(WrappedComponent: React.ComponentType<T>): {
     (props: Omit<T, keyof WithReCaptchaProps>): React.JSX.Element;
     displayName: string;
 };
-export { withReCaptcha };
-export type { WithReCaptchaProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-recaptcha-v3",
-  "version": "1.5.2",
+  "version": "2.0.0-beta.1",
   "description": "🤖 Next.js hook to add Google ReCaptcha to your application",
   "license": "MIT",
   "author": "Roman Zhuravlov",
@@ -38,27 +38,31 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@rollup/plugin-node-resolve": "^15.3.0",
-    "@rollup/plugin-typescript": "^12.1.1",
-    "@types/node": "^22.10.2",
-    "@types/react": "^19.0.1",
-    "@types/react-dom": "^19.0.2",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.1",
-    "eslint-config-next": "^15.1.0",
-    "eslint-config-prettier": "^9.1.0",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.20.0",
+    "@next/eslint-plugin-next": "^15.1.7",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^22.13.4",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "eslint": "^9.20.1",
+    "eslint-config-next": "^15.1.7",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.1.0",
     "husky": "^9.1.7",
-    "lint-staged": "^15.2.11",
-    "next": "^15.1.0",
-    "prettier": "3.4.2",
+    "lint-staged": "^15.4.3",
+    "next": "^15.1.7",
+    "prettier": "3.5.1",
     "pretty-quick": "^4.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "rollup": "^4.28.1",
-    "rollup-plugin-node-externals": "^7.1.3",
+    "rollup": "^4.34.8",
+    "rollup-plugin-node-externals": "^8.0.0",
     "rollup-plugin-preserve-directives": "^0.4.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1"
   },
   "lint-staged": {
     "**/*.{js,jsx,ts,tsx}": [