A captcha generator by using skia-canvas module.
npm install captcha-canvasskia-canvas rendering engine. Generate secure, visually complex CAPTCHAs that are difficult for bots to solve while remaining accessible to humans.
skia-canvas:
bash
npm install skia-canvas
`
$3
`bash
npm install captcha-canvas
`
$3
- Node.js 14+
- Platform-specific requirements for skia-canvas (see skia-canvas documentation)
Quick Start
$3
`javascript
const fs = require("fs");
const { createCaptchaSync } = require("captcha-canvas");
// Generate a 300x100 captcha
const { image, text } = createCaptchaSync(300, 100);
fs.writeFileSync("captcha.png", image);
console.log("Captcha text:", text);
`
$3
`javascript
const { createCaptcha } = require("captcha-canvas");
async function generateCaptcha() {
const { image, text } = createCaptcha(300, 100);
const buffer = await image;
fs.writeFileSync("captcha.png", buffer);
console.log("Captcha text:", text);
}
`
API Guide
$3
Perfect for quick CAPTCHA generation with minimal configuration.
#### createCaptcha(width, height, options?)
Generates a CAPTCHA asynchronously.
`javascript
const { createCaptcha } = require("captcha-canvas");
const { image, text } = createCaptcha(400, 150, {
captcha: {
text: "HELLO",
size: 60,
color: "#2563eb"
},
decoy: {
total: 30,
opacity: 0.6
},
trace: {
color: "#dc2626",
size: 4
}
});
`
#### createCaptchaSync(width, height, options?)
Generates a CAPTCHA synchronously (faster, but no background image support).
`javascript
const { createCaptchaSync } = require("captcha-canvas");
const { image, text } = createCaptchaSync(400, 150, {
captcha: {
characters: 8,
size: 50,
color: "#059669"
}
});
`
$3
Provides a fluent interface for advanced CAPTCHA customization with method chaining.
#### Basic Usage
`javascript
const { CaptchaGenerator } = require("captcha-canvas");
const captcha = new CaptchaGenerator()
.setDimension(200, 500)
.setCaptcha({
text: "SECURE123",
font: "Arial",
size: 60,
color: "#1f2937"
})
.setTrace({
color: "#ef4444",
size: 3
})
.setDecoy({
total: 40,
opacity: 0.7
});
// Generate synchronously
const buffer = captcha.generateSync();
fs.writeFileSync("captcha.png", buffer);
// Or generate asynchronously (required for background images)
const asyncBuffer = await captcha.generate();
`
#### Method Chaining Examples
`javascript
// Complete customization
const captcha = new CaptchaGenerator()
.setDimension(250, 600)
.setBackground("./background.jpg")
.setCaptcha({
text: "CUSTOM",
font: "Comic Sans MS",
size: 70,
color: "#7c3aed",
skew: true,
rotate: 15,
opacity: 0.9
})
.setTrace({
color: "#dc2626",
size: 5,
opacity: 0.8
})
.setDecoy({
color: "#6b7280",
font: "Arial",
size: 30,
opacity: 0.4,
total: 50
});
const buffer = await captcha.generate();
`
#### Multi-Styled Text (Array Configuration)
Create CAPTCHAs with different styles for each character segment:
`javascript
const captcha = new CaptchaGenerator()
.setDimension(200, 400)
.setCaptcha([
{ text: "AB", color: "red", size: 60, font: "Arial" },
{ text: "CD", color: "blue", size: 60, font: "Helvetica" },
{ text: "EF", color: "green", size: 60, font: "Times" }
]);
console.log(captcha.text); // "ABCDEF"
`
$3
Low-level class for fine-grained control over the rendering process.
`javascript
const { Captcha } = require("captcha-canvas");
const captcha = new Captcha(600, 200, 8); // width, height, characters
// Build the captcha step by step
captcha.addDecoy({ total: 20, size: 40 });
captcha.drawCaptcha({ size: 50, color: "#1e40af" });
captcha.drawTrace({ color: "#dc2626", size: 4 });
captcha.addDecoy({ opacity: 0.3 }); // Add more decoys on top
// Get the result
const buffer = captcha.png;
console.log("Generated text:", captcha.text);
`
Configuration Options
$3
`javascript
{
text: "CUSTOM", // Custom text (overrides characters)
characters: 6, // Number of random characters to generate
font: "Arial", // Font family
size: 60, // Font size in pixels
color: "#000000", // Text color (hex, rgb, or named)
colors: ["#ff0000", "#00ff00"], // Array of colors (overrides color)
skew: true, // Apply random skewing
rotate: 15, // Max rotation angle in degrees
opacity: 0.8 // Text opacity (0-1)
}
`
$3
`javascript
{
color: "#ff0000", // Line color
size: 3, // Line thickness
opacity: 1.0 // Line opacity (0-1)
}
`
$3
`javascript
{
color: "#cccccc", // Decoy color
font: "Arial", // Decoy font
size: 20, // Decoy size
opacity: 0.5, // Decoy opacity (0-1)
total: 30 // Number of decoy characters
}
`
$3
`javascript
captcha.setDimension(height, width);
// Example: captcha.setDimension(150, 400);
`
Examples
$3
`javascript
const express = require('express');
const { CaptchaGenerator } = require('captcha-canvas');
const app = express();
app.get('/captcha', async (req, res) => {
const captcha = new CaptchaGenerator()
.setDimension(100, 300)
.setCaptcha({ characters: 6 });
const buffer = captcha.generateSync();
// Store captcha.text in session for verification
req.session.captcha = captcha.text;
res.setHeader('Content-Type', 'image/png');
res.send(buffer);
});
app.post('/verify', (req, res) => {
const userInput = req.body.captcha;
const sessionCaptcha = req.session.captcha;
if (userInput === sessionCaptcha) {
res.json({ success: true });
} else {
res.json({ success: false });
}
});
`
$3
#### High Contrast CAPTCHA
`javascript
const captcha = new CaptchaGenerator()
.setDimension(120, 350)
.setCaptcha({
characters: 5,
font: "Impact",
size: 70,
color: "#ffffff",
skew: true,
rotate: 20
})
.setTrace({
color: "#ffffff",
size: 2,
opacity: 0.8
})
.setDecoy({
color: "#666666",
size: 25,
opacity: 0.3,
total: 20
});
`
#### Colorful CAPTCHA
`javascript
const captcha = new CaptchaGenerator()
.setDimension(150, 400)
.setCaptcha({
characters: 6,
font: "Comic Sans MS",
size: 60,
colors: ["#ff6b6b", "#4ecdc4", "#45b7d1", "#96ceb4", "#ffeaa7"],
skew: true,
rotate: 25
})
.setTrace({
color: "#2d3436",
size: 3
});
`
#### Background Image CAPTCHA
`javascript
const { resolveImage } = require('captcha-canvas');
async function createBackgroundCaptcha() {
const backgroundImage = await resolveImage('./pattern.jpg');
const captcha = new CaptchaGenerator()
.setDimension(200, 500)
.setBackground('./pattern.jpg')
.setCaptcha({
text: "SECURE",
size: 80,
color: "#ffffff",
opacity: 0.9
});
return await captcha.generate();
}
`
$3
`javascript
const captcha = new CaptchaGenerator()
.setDimension(180, 500)
.setCaptcha([
{
text: "SEC",
color: "#e74c3c",
size: 70,
font: "Impact",
rotate: 10
},
{
text: "URE",
color: "#3498db",
size: 70,
font: "Arial Black",
rotate: -10
}
])
.setTrace({
color: "#2c3e50",
size: 4
})
.setDecoy({
total: 35,
opacity: 0.4
});
console.log(captcha.text); // "SECURE"
`
Best Practices
$3
1. Always validate server-side: Never trust client-side CAPTCHA validation
2. Use session storage: Store the correct answer in server-side sessions
3. Implement rate limiting: Prevent brute force attacks
4. Add expiration: Set time limits for CAPTCHA validity
5. Use HTTPS: Protect CAPTCHA images and validation requests
`javascript
// Example with expiration
app.get('/captcha', (req, res) => {
const captcha = new CaptchaGenerator().setCaptcha({ characters: 6 });
const buffer = captcha.generateSync();
req.session.captcha = {
text: captcha.text,
expires: Date.now() + 300000 // 5 minutes
};
res.setHeader('Content-Type', 'image/png');
res.send(buffer);
});
app.post('/verify', (req, res) => {
const session = req.session.captcha;
if (!session || Date.now() > session.expires) {
return res.json({ success: false, error: 'CAPTCHA expired' });
}
const isValid = req.body.captcha === session.text;
delete req.session.captcha; // Clear after use
res.json({ success: isValid });
});
`
$3
1. Use sync generation when possible: Faster for simple CAPTCHAs without backgrounds
2. Cache background images: Load background images once and reuse
3. Optimize dimensions: Larger images take more processing time
4. Limit decoy characters: Too many decoys can impact performance
$3
1. Provide audio alternatives: Consider implementing audio CAPTCHAs
2. Use sufficient contrast: Ensure text is readable for visually impaired users
3. Offer refresh options: Allow users to generate new CAPTCHAs
4. Consider alternative verification: Implement fallback verification methods
Troubleshooting
$3
#### "Cannot find module 'skia-canvas'"
`bash
Install the peer dependency
npm install skia-canvas
`
#### "Error: Canvas creation failed"
This usually indicates a problem with skia-canvas installation. Try:
`bash
Reinstall skia-canvas
npm uninstall skia-canvas
npm install skia-canvas
On some systems, you might need:
npm install skia-canvas --build-from-source
`
#### Background images not working
Ensure you're using the async generate() method:
`javascript
// ❌ Wrong - sync method doesn't support backgrounds
captcha.setBackground('./bg.jpg');
const buffer = captcha.generateSync(); // Background ignored
// ✅ Correct - async method supports backgrounds
captcha.setBackground('./bg.jpg');
const buffer = await captcha.generate();
`
#### "Size of text and no. of characters is not matching"
This error occurs when you specify both text and characters with mismatched lengths:
`javascript
// ❌ Wrong - text length (5) doesn't match characters (6)
captcha.setCaptcha({
text: "HELLO",
characters: 6
});
// ✅ Correct - let the library handle character count
captcha.setCaptcha({
text: "HELLO"
});
// ✅ Or specify only character count for random text
captcha.setCaptcha({
characters: 6
});
`
$3
#### Windows
- Ensure Visual Studio Build Tools are installed
- Use Node.js 14+ with npm 6+
#### macOS
- Install Xcode Command Line Tools: xcode-select --install
#### Linux
- Install required system dependencies for skia-canvas
- See skia-canvas Linux requirements
API Reference
For complete API documentation with all methods, properties, and type definitions, visit:
📚 Full API Documentation
$3
#### Classes
- CaptchaGenerator - High-level fluent interface
- Captcha - Low-level canvas manipulation
#### Functions
- createCaptcha(width, height, options?) - Async simple generation
- createCaptchaSync(width, height, options?) - Sync simple generation
- resolveImage(path) - Load images for backgrounds
#### Key Methods
- .setDimension(height, width) - Set canvas size
- .setCaptcha(options) - Configure text appearance
- .setTrace(options) - Configure trace line
- .setDecoy(options) - Configure decoy characters
- .setBackground(image) - Set background image
- .generate() - Generate async (supports backgrounds)
- .generateSync() - Generate sync (faster, no backgrounds)
Contributing
We welcome contributions! Here's how you can help:
$3
`bash
Clone the repository
git clone https://github.com/Shashank3736/captcha-canvas.git
cd captcha-canvas
Install dependencies
npm install
Build the project
npm run build
Run examples
npm run example
Generate documentation
npm run docsgen
``