kit·intermediate·updated 2026-07-09

CAPTCHAs Kit

Bot protection that works. No third-party dependencies.

Next.jsNode.jsRedis

Generate and validate CAPTCHAs on your own server. Image generation, audio fallback, and rate limiting built in. Privacy-first, no tracking.

Install

~60 seconds

terminal

bash

git clone https://github.com/yashthakur1/cap.git my-captcha
cd my-captcha
npm install

~/ what's inside

Already wired, so you can skip to features.

Image and audio CAPTCHAs

Generate distorted text images and audio alternatives for accessibility.

Self-hosted validation

No external API calls. Verify challenges on your own infrastructure.

Rate limiting

Built-in Redis integration to prevent brute-force attacks and abuse.

~/ the stack behind it

Every dependency has a reason.

Next.js 16
API routes for CAPTCHA generation and validation.
Node.js
Canvas API for server-side image rendering.
Redis
Session storage and rate limiting.

~/ environment

Here's every env var, labeled.

Copy to .env.local. The included first-run script refuses to boot if any of them are missing — you'll know immediately.

.env.example

dotenv

NEXT_PUBLIC_APP_URL=http://localhost:3000
REDIS_URL=redis://localhost:6379
CAPTCHA_SECRET=your-secret-key-here
SESSION_TIMEOUT=300

~/ walkthrough

Zero to first deploy.

This is the exact sequence we'd run from a blank directory. Steps are reproducible — if one fails, we want to know.

1. Install dependencies
Clone the repo and install packages. Ensure Node.js 18+ is installed.
```
npm install
```

2. Set up Redis

Install Redis locally or use a managed service. Update REDIS_URL in .env.local.

# macOS
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis

3. Configure environment
Copy .env.example to .env.local and set CAPTCHA_SECRET to a random string. This key encrypts CAPTCHA sessions.
4. Run development server
Start the Next.js dev server and visit /captcha/demo to test generation and validation.
```
npm run dev
```

~/ known gotchas

The stuff that ate our afternoons.

Things we'd have wanted a heads-up on. Logged as we hit them.

!Canvas library requires native dependencies — install build tools (python, make, gcc) if npm install fails.
!Redis must be running before starting the dev server. Check with 'redis-cli ping'.
!CAPTCHA_SECRET must be the same across all server instances for distributed deployments.
!Audio CAPTCHAs use text-to-speech — verify ffmpeg is installed for audio generation.

when not

If you need advanced bot detection (behavioral analysis, risk scoring), consider a managed service like hCaptcha or Cloudflare Turnstile. This kit focuses on simple, self-hosted challenge-response.

license: MIT·star on github →

Got stuck, or want this shipped end-to-end for you? bitroot.club builds custom products for founders. →