Registry / web-framework / express-recaptcha

express-recaptcha

library5.1.0jsnpmunverified

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.

web-framework auth-security

npm install express-recaptcha

github ↗package ↗

INSTALL

IMPORT

SIG · EXPRESS-RECAPTCHA

express-recaptcha

web-frameworkjavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RecaptchaV3

✓ import { RecaptchaV3 } from 'express-recaptcha'

✗ const RecaptchaV3 = require('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

✓ import { RecaptchaV2 } from 'express-recaptcha'

✗ const Recaptcha = require('express-recaptcha')

If using CommonJS, correct import is: const { RecaptchaV2 } = require('express-recaptcha').

init

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

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

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

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);

Debug

Known issues

breakingv3.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).

affects: >=3.0.0 <4.0.0

breakingv3.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.

affects: >=3.0.0 <4.0.0

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

fix

Refer to v3 changelog for updated verify result format.

affects: >=3.0.0 <4.0.0

deprecatedv4.0.0: TypeScript definitions are now included.

fix

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

affects: >=4.0.0

gotchaThe 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.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: Recaptcha is not a constructor

Using Recaptcha from CommonJS require without destructuring the named export.

fix

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

recaptcha.middleware.render is not a function

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

fix

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

Cannot find module 'express-recaptcha'

Package not installed or wrong import path.

fix

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

req.recaptcha is undefined

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

fix

Use res.recaptcha in your templates or handlers.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

expressrequiredPeer dependency; middleware is designed to work with express

Agent activity

31 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/pdupavillon/express-recaptcha ↗

packagehttps://www.npmjs.com/package/express-recaptcha ↗