@hcaptcha/react-hcaptcha 1.4.3 → 1.5.0

package/README.md

@@ -1,13 +1,19 @@
 # React hCaptcha Component Library
 
-## Description
 
 hCaptcha Component Library for ReactJS.
 
-[hCaptcha](https://www.hcaptcha.com) is a drop-replacement for reCAPTCHA that protects user privacy, rewards websites, and helps companies get their data labeled.
+[hCaptcha](https://www.hcaptcha.com) is a drop-replacement for reCAPTCHA that protects user privacy.
 
 Sign up at [hCaptcha](https://www.hcaptcha.com) to get your sitekey today. **You need a sitekey to use this library.**
 
+*Also compatible with Preact.*
+
+1. [Installation](#installation)
+2. [References](#references)
+3. [Debugging](#debugging)
+4. [Contributing](#contributing)
+
 ## Installation
 
 You can install this library via npm with:
@@ -16,11 +22,11 @@ You can install this library via npm with:
 npm install @hcaptcha/react-hcaptcha --save
 ```
 
-### Usage
+### Implementation
 The two requirements for usage are the `sitekey` [prop](#props) and a `parent component` such as a `<form />`. The component will automatically include and load the
 hCaptcha API library and append it to the parent component. This is designed for ease of use with the hCaptcha API!
 
-#### Basic Usage
+#### Standard
 
 ```js
 import HCaptcha from '@hcaptcha/react-hcaptcha';
@@ -33,21 +39,7 @@ import HCaptcha from '@hcaptcha/react-hcaptcha';
 </FormComponent>
 ```
 
-**A note about TypeScript usage:** If you want to reassign the component name, you could consider making a util that imports the component, then re-exports it as a default. Example:
-
-```ts
-// utils/captcha.ts
-import HCaptcha from '@hcaptcha/react-hcaptcha';
-export default HCaptcha;
-
-// MyFormComponent.tsx
-import { default as RenamedCaptcha } from '../utils/captcha';
-<FormComponent>
-  <RenamedCaptcha sitekey="your-sitekey" />
-</FormComponent>
-```
-
-#### Programmatic Usage
+#### Programmatic
 In the event you want to call the hCaptcha client API directly, you can do so by using the hook `useRef` and waiting for `onLoad` to be called. By waiting for `onLoad` the hCaptcha API will be ready and the hCaptcha client will have been setup. See the following example:
 
 ```js
@@ -86,7 +78,22 @@ export default function Form() {
 }
 ```
 
-#### Advanced usage
+**Typescript Support** \
+If you want to reassign the component name, you could consider making a util that imports the component, then re-exports it as a default.
+
+```ts
+// utils/captcha.ts
+import HCaptcha from '@hcaptcha/react-hcaptcha';
+export default HCaptcha;
+
+// MyFormComponent.tsx
+import { default as RenamedCaptcha } from '../utils/captcha';
+<FormComponent>
+  <RenamedCaptcha sitekey="your-sitekey" />
+</FormComponent>
+```
+
+#### Advanced
 
 In most real-world implementations, you'll probably be using a form library such as [Formik](https://github.com/jaredpalmer/formik) or [React Hook Form](https://github.com/react-hook-form/react-hook-form).
 
@@ -111,8 +118,9 @@ const onLoad = () => {
 return <HCaptcha ref={captchaRef} onLoad={onLoad} sitekey={sitekey} {...props} />;
 ```
 
+### References
 
-### Props
+#### Props
 
 |Name|Values/Type|Required|Default|Description|
 |---|---|---|---|---|
@@ -132,7 +140,7 @@ return <HCaptcha ref={captchaRef} onLoad={onLoad} sitekey={sitekey} {...props} /
 |`sentry`|String|No|`-`|See enterprise docs.|
 |`custom`|Boolean|No|`-`|See enterprise docs.|
 
-### Events
+#### Events
 
 |Event|Params|Description|
 |---|---|---|
@@ -144,7 +152,7 @@ return <HCaptcha ref={captchaRef} onLoad={onLoad} sitekey={sitekey} {...props} /
 |`onClose`|-|When the user dismisses a challenge.|
 |`onChalExpired`|-|When the user display of a challenge times out with no answer.|
 
-### Methods
+#### Methods
 
 |Method|Description|
 |---|---|
@@ -155,7 +163,8 @@ return <HCaptcha ref={captchaRef} onLoad={onLoad} sitekey={sitekey} {...props} /
 |`setData()`|See enterprise docs.|
 
 
-**NOTE**: Make sure to reset the hCaptcha state when you submit your form by calling the method `.resetCaptcha` on your hCaptcha React Component! Passcodes are one-time use, so if your user submits the same passcode twice then it will be rejected by the server the second time.
+> **Note** \
+> Make sure to reset the hCaptcha state when you submit your form by calling the method `.resetCaptcha` on your hCaptcha React Component! Passcodes are one-time use, so if your user submits the same passcode twice then it will be rejected by the server the second time.
 
 Please refer to the demo for examples of basic usage and an invisible hCaptcha.
 
@@ -163,9 +172,24 @@ Alternatively, see [this sandbox code](https://codesandbox.io/s/react-hcaptchafo
 
 Please note that "invisible" simply means that no hCaptcha button will be rendered. Whether a challenge shows up will depend on the sitekey difficulty level. Note to hCaptcha Enterprise ([BotStop](https://www.botstop.com)) users: select "Passive" or "99.9% Passive" modes to get this No-CAPTCHA behavior.
 
----
 
-### Note for maintainers
+
+
+### Debugging
+
+1. #### Invalid hCaptcha Id: <hcaptcha_id>
+    This issue generally occurs when the component is re-rendered causing the current `useRef` to become stale, meaning the `ref` being used is no longer available in the DOM.
+
+
+2. #### Make sure you don't double-import the api.js script
+    Importing the JS SDK twice can cause unpredictable behavior, so don't do a direct import separately if you are using react-hcaptcha.
+
+3. #### Make sure you are using `reCaptchaCompat=false` if you have the reCAPTCHA JS loaded on the same page.
+    The hCaptcha "compatibility mode" will interfere with reCAPTCHA, as it adds properties with the same name. If for any reason you are running both hCaptcha and reCAPTCHA in parallel (we recommend only running hCaptcha) then please disable our compatibility mode.
+
+
+---
+### Contributing
 
 #### Scripts
 
@@ -188,8 +212,9 @@ Please see: [Local Development Notes](https://docs.hcaptcha.com/#localdev).
 
 Summary:
 
-`sudo echo "127.0.0.1 fakelocal.com" >> /private/etc/hosts`
-
-`npm start -- --disable-host-check`
+```
+sudo echo "127.0.0.1 fakelocal.com" >> /private/etc/hosts
+npm start -- --disable-host-check
+```
 
 open [http://fakelocal.com:9000](http://fakelocal.com:9000) to start the example.

package/dist/esm/index.js

@@ -29,7 +29,8 @@ var mountCaptchaScript = function mountCaptchaScript(params) {
   var script = document.createElement("script");
   script.id = SCRIPT_ID;
   script.src = domain + "/1/api.js?render=explicit&onload=" + HCAPTCHA_LOAD_FN_NAME;
-  script.async = true;
+  script.async = params.loadAsync !== undefined ? params.loadAsync : true;
+  delete params.loadAsync;
 
   script.onerror = function (event) {
     return rejectFn('script-error');
@@ -146,7 +147,8 @@ var HCaptcha = /*#__PURE__*/function (_React$Component) {
         reCaptchaCompat = _this$props.reCaptchaCompat,
         reportapi = _this$props.reportapi,
         sentry = _this$props.sentry,
-        custom = _this$props.custom;
+        custom = _this$props.custom,
+        loadAsync = _this$props.loadAsync;
     var mountParams = {
       apihost: apihost,
       assethost: assethost,
@@ -157,7 +159,8 @@ var HCaptcha = /*#__PURE__*/function (_React$Component) {
       recaptchacompat: reCaptchaCompat === false ? "off" : null,
       reportapi: reportapi,
       sentry: sentry,
-      custom: custom
+      custom: custom,
+      loadAsync: loadAsync
     };
     mountCaptchaScript(mountParams).then(this.handleOnLoad)["catch"](this.handleError);
     this.apiScriptRequested = true;

package/dist/index.js

@@ -56,7 +56,8 @@ var mountCaptchaScript = function mountCaptchaScript() {
   var script = document.createElement("script");
   script.id = SCRIPT_ID;
   script.src = "".concat(domain, "/1/api.js?render=explicit&onload=").concat(HCAPTCHA_LOAD_FN_NAME);
-  script.async = true;
+  script.async = params.loadAsync !== undefined ? params.loadAsync : true;
+  delete params.loadAsync;
 
   script.onerror = function (event) {
     return rejectFn('script-error');
@@ -180,7 +181,8 @@ var HCaptcha = /*#__PURE__*/function (_React$Component) {
           reCaptchaCompat = _this$props.reCaptchaCompat,
           reportapi = _this$props.reportapi,
           sentry = _this$props.sentry,
-          custom = _this$props.custom;
+          custom = _this$props.custom,
+          loadAsync = _this$props.loadAsync;
       var mountParams = {
         apihost: apihost,
         assethost: assethost,
@@ -191,7 +193,8 @@ var HCaptcha = /*#__PURE__*/function (_React$Component) {
         recaptchacompat: reCaptchaCompat === false ? "off" : null,
         reportapi: reportapi,
         sentry: sentry,
-        custom: custom
+        custom: custom,
+        loadAsync: loadAsync
       };
       mountCaptchaScript(mountParams).then(this.handleOnLoad)["catch"](this.handleError);
       this.apiScriptRequested = true;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@hcaptcha/react-hcaptcha",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "types": "types/index.d.ts",
+  "type": "module",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
   "files": [
@@ -11,7 +12,7 @@
   ],
   "description": "A React library for hCaptcha",
   "scripts": {
-    "start": "webpack-dev-server --config ./webpack.config.js --mode development",
+    "start": "webpack serve",
     "test": "jest",
     "watch": "babel src -d dist --copy-files --watch",
     "transpile": "babel src -d dist --copy-files",
@@ -31,27 +32,33 @@
     "captcha"
   ],
   "author": "hCaptcha team and contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hCaptcha/react-hcaptcha.git"
+  },
   "license": "MIT",
   "devDependencies": {
-    "@babel/cli": "^7.12.10",
+    "@babel/cli": "^7.12.1",
     "@babel/core": "^7.12.10",
     "@babel/plugin-transform-runtime": "^7.14.5",
     "@babel/preset-env": "^7.12.11",
     "@babel/preset-react": "^7.12.10",
+    "@jest/globals": "^29.5.0",
+    "@types/react": "^16.0.0",
     "babel-loader": "^8.2.2",
     "babel-plugin-add-module-exports": "^1.0.4",
     "cross-env": "^7.0.3",
-    "html-webpack-plugin": "^3.2.0",
-    "jest": "^26.6.3",
+    "html-webpack-plugin": "^5.5.0",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
     "react": "^16.14.0",
     "react-dom": "^16.14.0",
     "rimraf": "^3.0.2",
-    "webpack": "^4.44.2",
-    "webpack-cli": "^3.3.12",
-    "webpack-dev-server": "^3.11.0"
+    "webpack": "^5.76.3",
+    "webpack-cli": "^5.0.1",
+    "webpack-dev-server": "^4.13.1"
   },
   "dependencies": {
-    "@babel/runtime": "^7.17.9",
-    "@types/react": "^18.0.0"
+    "@babel/runtime": "^7.17.9"
   }
 }

package/src/index.js

@@ -28,7 +28,10 @@ const mountCaptchaScript = (params={}) => {
   const script = document.createElement("script");
   script.id = SCRIPT_ID;
   script.src = `${domain}/1/api.js?render=explicit&onload=${HCAPTCHA_LOAD_FN_NAME}`;
-  script.async = true;
+
+  script.async = params.loadAsync !== undefined? params.loadAsync : true;
+  delete params.loadAsync;
+
   script.onerror = (event) => rejectFn('script-error');
 
   const query = generateQuery(params);
@@ -139,7 +142,8 @@ class HCaptcha extends React.Component {
         reCaptchaCompat,
         reportapi,
         sentry,
-        custom
+        custom,
+        loadAsync
       } = this.props;
       const mountParams = {
         apihost,
@@ -151,7 +155,8 @@ class HCaptcha extends React.Component {
         recaptchacompat: reCaptchaCompat === false? "off" : null,
         reportapi,
         sentry,
-        custom
+        custom,
+        loadAsync
       };
 
       mountCaptchaScript(mountParams)
@@ -323,7 +328,7 @@ class HCaptcha extends React.Component {
 
     render () {
       const { elementId } = this.state;
-      return <div ref={this.ref} id={elementId}></div>
+      return <div ref={this.ref} id={elementId}></div>;
     }
   }
 

package/types/index.d.ts

@@ -28,6 +28,7 @@ interface HCaptchaProps {
   tabIndex?: number;
   id?: string;
   reCaptchaCompat?: boolean;
+  loadAsync?: boolean;
 }
 
 interface ExecuteResponse {