express-recaptcha

5.1.0 verified Sat Apr 25 auth: no javascript

Express middleware for Google reCAPTCHA integration (v2 and v3). Current stable version is 5.1.0, with TypeScript support added in v4.0.0. The library provides simple middleware methods to render captcha widgets and verify tokens. v3.0.0 introduced breaking changes: the module now exports a class constructor instead of an instance, the 'recaptcha' property is set on the response object rather than the request, and the verify result format changed. Alternative packages include 'recaptcha-v2' and 'google-recaptcha', but express-recaptcha offers a straightforward express-centric API.

Common errors

error TypeError: Recaptcha is not a constructor ↓

cause Using Recaptcha from CommonJS require without destructuring the named export.

fix

Use: const { RecaptchaV3 } = require('express-recaptcha'); then new RecaptchaV3(...).

error recaptcha.middleware.render is not a function ↓

cause The Recaptcha instance was created incorrectly, possibly due to using older API.

fix

Ensure you created instance with new RecaptchaV3(site, secret) (v3+).

error Cannot find module 'express-recaptcha' ↓

cause Package not installed or wrong import path.

fix

Run npm install express-recaptcha and check the import statement.

error req.recaptcha is undefined ↓

cause In v3+, recaptcha is set on response object, not request.

fix

Use res.recaptcha in your templates or handlers.

Warnings

breaking v3.0.0: express-recaptcha now returns a class instead of an instance; the 'init' function is removed. All parameters must be passed to the constructor. ↓

fix Replace Recaptcha.init(site, secret) with new Recaptcha(site, secret).

breaking v3.0.0: The render method now sets the 'recaptcha' property on the response object (res.recaptcha) instead of the request object (req.recaptcha). ↓

fix Update your templates to use res.recaptcha instead of req.recaptcha.

breaking v3.0.0: The object returned from the verify middleware has changed; check new structure. ↓

fix Refer to v3 changelog for updated verify result format.

deprecated v4.0.0: TypeScript definitions are now included. ↓

fix No action needed; but if using @types/express-recaptcha, remove it.

gotcha The CommonJS require returns an object with named exports; default import is not available. Use const { RecaptchaV3 } = require('express-recaptcha'); ↓

fix Use named import or destructure the require result.

Install

npm install express-recaptcha

yarn add express-recaptcha

pnpm add express-recaptcha

Imports

RecaptchaV3
wrong
```
const RecaptchaV3 = require('express-recaptcha')
```
correct
```
import { RecaptchaV3 } from 'express-recaptcha'
```
Since v4.0.0, library ships TypeScript types. Use named import for RecaptchaV3 or RecaptchaV2. CommonJS require will not work with default export; use .RecaptchaV3.
RecaptchaV2
wrong
```
const Recaptcha = require('express-recaptcha')
```
correct
```
import { RecaptchaV2 } from 'express-recaptcha'
```
If using CommonJS, correct import is: const { RecaptchaV2 } = require('express-recaptcha').

init

wrong

Recaptcha.init('site_key', 'secret_key')

correct

const recaptcha = new RecaptchaV3('site_key', 'secret_key')

v3.0.0+ removed the 'init' function. Use constructor directly.

Quickstart

Shows how to use RecaptchaV3 middleware to render captcha and verify token in Express routes.

import { RecaptchaV3 } from 'express-recaptcha';
import express from 'express';

const app = express();
const recaptcha = new RecaptchaV3(process.env.RECAPTCHA_SITE_KEY ?? '', process.env.RECAPTCHA_SECRET_KEY ?? '');

app.use(express.urlencoded({ extended: false }));
app.use(express.json());

app.get('/', recaptcha.middleware.render, (req, res) => {
  res.send(`<html><body>${res.recaptcha}</body></html>`);
});

app.post('/verify', recaptcha.middleware.verify, (req, res) => {
  if (req.recaptcha.error) {
    return res.send(`Verification failed: ${req.recaptcha.error}`);
  }
  res.send('Success');
});

app.listen(3000);