NextCaptcha

Behavior Captcha Of Node.js

English | 中文

next-captcha is a powerful, modular, and highly customizable behavioral CAPTCHA library for Node.js that supports multiple interactive CAPTCHA types: Click, Slide, Drag-Drop, and Rotate.

⭐️ If it helps you, please give a star.

Ecosystem

Core Features

• Diverse CAPTCHA Types: Supports Click, Slide, Rotate, and Drag-Drop behavioral CAPTCHAs for different interaction scenarios.
• Highly Customizable: Flexible configuration of images, fonts, colors, angles, sizes, and behavior through options and resources.
• Advanced Image Processing: Supports dynamic generation of master images, thumbnails, puzzle tiles, masks, and shadow effects.
• Modular Architecture: Clear module boundaries for click, slide, slide-region, rotate, and shared base utilities.
• TypeScript-Friendly Design: Ships with TypeScript declarations and works with CommonJS, native ESM, and TypeScript imports.
• Cross-Platform Integration: Generated CAPTCHA images can be used in web applications, Node.js services, APIs, or hybrid app backends.

CAPTCHA Types

next-captcha supports the following four CAPTCHA types, each with its own interaction style, generation logic, and usage scenario:

1. Click CAPTCHA: Users click specified text or shape targets on the master image, supporting text mode and shape mode.
2. Slide CAPTCHA: Users slide a puzzle tile to the correct position on the master image, supporting basic mode and drag-drop mode.
3. Drag-Drop CAPTCHA: A variant of the Slide CAPTCHA, allowing freer tile movement over a larger interaction area.
4. Rotate CAPTCHA: Users rotate a thumbnail to visually align it with the master image angle.

Installation

npm install next-captcha

Runtime Requirements

• Node.js 14+
• A platform supported by @napi-rs/canvas

Importing Modules

CommonJS

const { ClickBuilder } = require('next-captcha');
const Click = require('next-captcha/click');

Native ESM

import { ClickBuilder } from 'next-captcha';
import * as Click from 'next-captcha/click';

TypeScript

import { ClickBuilder, loadImageFromPath } from 'next-captcha';
import { withChars, withBackgrounds } from 'next-captcha/click';

Package Exports

• next-captcha
• next-captcha/click
• next-captcha/slide
• next-captcha/slide-region
• next-captcha/rotate
• next-captcha/base/tools ← recommended for public image/font helpers
• next-captcha/base/canvas-adapter ← advanced adapter customization only

Module Format Support

After build, the package publishes:

• CommonJS for require()
• Native ESM for import
• TypeScript declarations for both styles

Base Utility Helpers

For normal consumers, prefer loadImageFromPath, loadImageFromBuffer, and registerFontFromPath from the main package entry, or use next-captcha/base/tools if you prefer subpath imports.

To keep from importing @napi-rs/canvas directly, the package exposes public helper utilities under next-captcha/base/tools:

• loadImageFromPath(path)
• loadImageFromBuffer(buffer)
• registerFontFromPath(path, fontFace)

These helpers are built on top of the internal canvas adapter and are the recommended public API for loading images and registering fonts.

Click CAPTCHA

Click CAPTCHA asks the user to click specific targets on the master image.

Modes:

• Text Mode: clickable characters
• Shape Mode: clickable icons or shapes

How It Works

1. Generate the master image (masterImage) with random items.
2. Generate the thumbnail image (thumbImage) showing verification targets.
3. The frontend captures click coordinates.
4. The backend validates coordinates against the generated dots data.

Example: Text Click CAPTCHA

import { ClickBuilder, loadImageFromPath } from 'next-captcha';
import {
  withBackgrounds,
  withChars,
  withRangeLen,
  withRangeVerifyLen,
} from 'next-captcha/click';
import { loadImageFromPath } from 'next-captcha/base/tools';

const builder = new ClickBuilder();

builder.setOptions(
  withRangeLen({ min: 4, max: 6 }),
  withRangeVerifyLen({ min: 2, max: 4 })
);

builder.setResources(
  withChars(['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H']),
  withBackgrounds([await loadImageFromPath('bg.png')])
);

const captcha = builder.make();
const data = await captcha.generate();

const dots = data.getData();
const masterImage = await data.getMasterImage().toBuffer();
const thumbImage = await data.getThumbImage().toBuffer();

Example: Shape Click CAPTCHA

import { ClickBuilder, loadImageFromPath } from 'next-captcha';
import { withBackgrounds, withShapes } from 'next-captcha/click';
import { loadImageFromPath } from 'next-captcha/base/tools';

const builder = new ClickBuilder();

builder.setResources(
  withBackgrounds([await loadImageFromPath('bg.png')]),
  withShapes(
    new Map([
      ['star', await loadImageFromPath('star.png')],
      ['heart', await loadImageFromPath('heart.png')],
      ['moon', await loadImageFromPath('moon.png')],
      ['cloud', await loadImageFromPath('cloud.png')],
      ['leaf', await loadImageFromPath('leaf.png')],
      ['sun', await loadImageFromPath('sun.png')],
    ])
  )
);

const captcha = builder.makeShape();
const data = await captcha.generate();

Create Instance

• builder.make() → text click CAPTCHA
• builder.makeShape() → shape click CAPTCHA

Click Options

Click Resources

Click Captcha Data

Click Validation

import { validate as validateClick } from 'next-captcha/click';
const ok = validateClick(srcX, srcY, x, y, width, height, padding);

Slide CAPTCHA / Drag-Drop CAPTCHA

Slide CAPTCHA asks the user to move a tile into the correct position.

Modes:

• Basic Mode: horizontal slide with fixed Y-axis behavior
• Drag-Drop Mode: freer drag positioning

Example

import { SlideBuilder, loadImageFromPath } from 'next-captcha';
import { withBackgrounds, withGraphImages } from 'next-captcha/slide';
import { loadImageFromPath } from 'next-captcha/base/tools';

const builder = new SlideBuilder();

builder.setResources(
  withBackgrounds([await loadImageFromPath('bg.png')]),
  withGraphImages([
    {
      overlayImage: await loadImageFromPath('tile.png'),
      shadowImage: await loadImageFromPath('tile-shadow.png'),
      maskImage: await loadImageFromPath('tile-mask.png'),
    },
  ])
);

const captcha = builder.make();
const data = await captcha.generate();

Drag-Drop Example

import { SlideRegionBuilder } from 'next-captcha/slide-region';

const builder = new SlideRegionBuilder();
const captcha = builder.makeDragDrop();

Create Instance

• builder.make() → basic slide CAPTCHA
• builder.makeDragDrop() → drag-drop CAPTCHA

Slide Options

Slide Resources

Slide Captcha Data

Slide Validation

import { validate as validateSlide } from 'next-captcha/slide';
const ok = validateSlide(srcX, srcY, x, y, padding);

Drag-Drop Alias Module

next-captcha/slide-region also provides:

• SlideRegionBuilder
• SlideRegionCaptcha
• newSlideRegionBuilder()

Rotate CAPTCHA

Rotate CAPTCHA asks the user to rotate a thumbnail image until it visually matches the master image.

Example

import { RotateBuilder, loadImageFromPath } from 'next-captcha';
import { withImages, withRangeAnglePos } from 'next-captcha/rotate';
import { loadImageFromPath } from 'next-captcha/base/tools';

const builder = new RotateBuilder();

builder.setOptions(
  withRangeAnglePos([{ min: 30, max: 330 }])
);

builder.setResources(
  withImages([
    await loadImageFromPath('rotate-bg-1.png'),
    await loadImageFromPath('rotate-bg-2.png'),
  ])
);

const captcha = builder.make();
const data = await captcha.generate();

Rotate Options

Rotate Resources

Rotate Captcha Data

Rotate Validation

import { validate as validateRotate } from 'next-captcha/rotate';
const ok = validateRotate(userAngle, targetAngle, padding);

Validation Helpers from Main Entry

import { validateClick, validateSlide, validateRotate } from 'next-captcha';

License

Apache-2.0