Quickstart

This guide walks you through building a complete Ribaunt CAPTCHA integration: two server endpoints that issue and verify proof-of-work challenges, plus a browser widget your users interact with. By the end you’ll have a working bot-protection layer you can drop in front of any form or API action.

Install Ribaunt

Add the ribaunt package to your project.

npm install ribaunt

yarn add ribaunt

pnpm add ribaunt

Set your secret

Ribaunt signs every challenge token with a secret you control. Add RIBAUNT_SECRET to your server environment — a .env file, your hosting platform’s secrets manager, or however you manage server config.

RIBAUNT_SECRET="replace-with-a-long-random-secret"

Keep RIBAUNT_SECRET server-only. Never expose it to the browser. In Next.js, do not prefix it with NEXT_PUBLIC_ — that would embed the secret in your client bundle and allow anyone to forge valid challenge tokens.

Create server endpoints

You need two endpoints: one that issues challenges and one that verifies solutions. Here is a complete Express example using the current createChallenge and verifySolution APIs from ribaunt.

import 'dotenv/config';
import express from 'express';
import { createChallenge, verifySolution } from 'ribaunt';

const app = express();
app.use(express.json());

app.get('/api/captcha/challenge', (_req, res) => {
  const challenges = createChallenge({
    difficulty: 5,
    amount: 4,
    ttlSeconds: 120,
    context: 'signup',
  });

  res.json({ challenges });
});

app.post('/api/captcha/verify', async (req, res) => {
  const { tokens, solutions } = req.body;
  const result = await verifySolution(tokens, solutions, { context: 'signup' });

  if (!result.valid) {
    return res.status(400).json({ success: false, error: result.reason, message: result.message });
  }

  return res.json({ success: true });
});

app.listen(3000);

createChallenge() accepts either positional arguments or an options object. The options object supports difficulty, amount, ttlSeconds, context, and an adaptive workload configuration.verifySolution() now returns a structured result object instead of a bare boolean. Check result.valid and use result.reason or result.message when verification fails.

Add the widget to your frontend

Include the Ribaunt web component script and place the <ribaunt-widget> element wherever you need CAPTCHA protection. The widget fetches a challenge from your server, solves it in the browser, and sends the solutions back to your verify endpoint when auto-verify="true" is set.

<script type="module" src="/node_modules/ribaunt/dist/widget-browser.js"></script>

<ribaunt-widget
  challenge-endpoint="/api/captcha/challenge"
  verify-endpoint="/api/captcha/verify"
  auto-verify="true"
  solve-timeout="15000"
></ribaunt-widget>

<script>
  const widget = document.querySelector('ribaunt-widget');

  widget.addEventListener('verify', (event) => {
    console.log('Verified!', event.detail.solutions);
  });
</script>

If you’re using React, import the wrapper component instead of the web component directly. See React Integration for the full example.

The widget emits a verify event when the challenge is solved. A corresponding error event fires if verification fails, and state-change reports intermediate states such as fetching, solving, verifying, and done.

Next steps

Widget configuration

Explore all widget attributes — timeouts, worker mode, challenge method, calibration, theming, and the disabled state.

React integration

Use the ribaunt/widget-react wrapper with full prop support in React and Next.js App Router.

Express server example

A production-ready Express server setup with replay protection, structured warnings, and context-aware verification.

Get Started

Core Concepts

Server Setup

Frontend Integration

Widget

Guides

Next steps

Widget configuration

React integration

Express server example

​Next steps

Widget configuration

React integration

Express server example

Next steps