captcha-canvas - v2.4.2

captcha-canvas API Documentation

Welcome to the comprehensive API documentation for captcha-canvas - a powerful Node.js library for generating secure, customizable CAPTCHA images.

📦 Installation

# Install the canvas peer dependency first
npm install canvas

# Install captcha-canvas
npm install captcha-canvas

🎯 Getting Started

Basic Usage

import { CaptchaGenerator } from 'captcha-canvas';

// Create a simple captcha
const captcha = new CaptchaGenerator()
  .setDimension(150, 400)
  .setCaptcha({ size: 60, color: 'blue' });

const buffer = await captcha.generate();
console.log('Captcha text:', captcha.text);

Advanced Configuration

import { CaptchaGenerator } from 'captcha-canvas';

// Create a highly customized captcha
const captcha = new CaptchaGenerator({ height: 200, width: 500 })
  .setCaptcha({
    text: 'SECURE',
    colors: ['#ff6b6b', '#4ecdc4', '#45b7d1'],
    font: 'Arial',
    size: 70,
    rotate: 15,
    skew: true
  })
  .setTrace({
    color: '#ff6b6b',
    size: 4,
    opacity: 0.7
  })
  .setDecoy({
    opacity: 0.4,
    size: 25
  });

const buffer = await captcha.generate();

🎨 Key Features

🔧 Highly Customizable

Text Styling: Control font, size, color, rotation, and skewing
Visual Effects: Add trace lines and decoy characters
Background Images: Support for custom background images
Segmented Text: Apply different styles to different parts of the text

🛡️ Security Focused

OCR Resistance: 95% failure rate against automated OCR systems
Visual Distortions: Multiple layers of visual complexity
Random Generation: Cryptographically secure random text generation

⚡ Developer Friendly

Dual API: Simple functions and advanced class-based approach
TypeScript Support: Full type definitions included
Async/Sync: Both asynchronous and synchronous generation methods
Method Chaining: Fluent interface for easy configuration

📚 Examples

Segmented Styling

Apply different styles to different parts of your captcha text:

const captcha = new CaptchaGenerator()
  .setDimension(150, 450)
  .setCaptcha([
    { text: 'SEC', color: '#e74c3c', size: 60, start: 0, end: 3 },
    { text: 'URE', color: '#3498db', size: 50, start: 3, end: 6 }
  ]);

const buffer = await captcha.generate();
console.log('Text:', captcha.text); // "SECURE"

With Background Image

Add visual complexity with background images:

import fs from 'fs';

const backgroundBuffer = fs.readFileSync('./background.jpg');

const captcha = new CaptchaGenerator()
  .setDimension(200, 400)
  .setBackground(backgroundBuffer)
  .setCaptcha({
    color: 'white',
    size: 50,
    opacity: 0.9
  });

const buffer = await captcha.generate();

Express.js Integration

Perfect for web applications:

import express from 'express';
import { CaptchaGenerator } from 'captcha-canvas';

const app = express();

app.get('/captcha', async (req, res) => {
  const captcha = new CaptchaGenerator()
    .setDimension(150, 400)
    .setCaptcha({ size: 60 });

  // Store in session for verification
  req.session.captcha = captcha.text;

  const buffer = await captcha.generate();
  res.setHeader('Content-Type', 'image/png');
  res.send(buffer);
});