Zum Hauptinhalt springen
Ribaunts React-Wrapper unter ribaunt/widget-react kümmert sich automatisch um SSR-Guards, indem er die ausschließlich im Browser laufende Web-Komponente dynamisch auf dem Client importiert. Füge 'use client' zu deiner Komponentendatei hinzu, importiere RibauntWidget, und schon kann es losgehen – keine zusätzliche Konfiguration erforderlich.
Präfixiere RIBAUNT_SECRET niemals mit NEXT_PUBLIC_.
Dadurch wird das Secret in dein Client-Bundle eingebettet und für jeden Besucher offengelegt. Halte RIBAUNT_SECRET in .env.local ohne das Präfix NEXT_PUBLIC_, damit es ausschließlich auf dem Server bleibt.

​
Einrichtung der Client-Komponente

Erstelle eine Client-Komponente und füge RibauntWidget ein. Da der Wrapper den dynamischen Import intern handhabt, musst du ihn nicht in next/dynamic einpacken. 
'use client';

import { useRef } from 'react';
import RibauntWidget, { type RibauntWidgetHandle } from 'ribaunt/widget-react';

export default function ContactForm() {
  const widgetRef = useRef<RibauntWidgetHandle>(null);

  return (
    <form>
      <RibauntWidget
        ref={widgetRef}
        challengeEndpoint="/api/captcha/challenge"
        verifyEndpoint="/api/captcha/verify"
        autoVerify={true}
        solveTimeout={15000}
        onVerify={(detail) => console.log('Verified:', detail.solutions)}
        onError={(detail) => console.error('Failed:', detail.error)}
        onReady={(detail) => console.log('Ready:', detail.state)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
NICHT in next/dynamic einpacken – der ribaunt/widget-react-Wrapper kümmert sich bereits intern um den dynamischen Import. Ein zusätzlicher next/dynamic-Aufruf ist unnötig und kann zu doppeltem Laden führen.

​
API-Routen

Die oben gezeigte Client-Komponente ruft /api/captcha/challenge und /api/captcha/verify auf. Du musst diese serverseitigen Endpunkte erstellen, um Challenges zu generieren und Lösungen zu validieren. Die vollständige Route-Handler-Implementierung findest du in der Next.js-Server-Anleitung.

​
Wichtige Überlegungen

  • Verwende immer 'use client' – RibauntWidget wird im Browser gerendert und basiert auf Browser-APIs.
  • Verwende next/dynamic nicht – der Wrapper handhabt den dynamischen Import von selbst; das Hinzufügen von next/dynamic ist redundant.
  • Lege RIBAUNT_SECRET nicht über NEXT_PUBLIC_ offen – das Secret muss ausschließlich serverseitig bleiben.
  • Verwende HTTPS oder localhost – das Lösen im Browser hängt von der Web Crypto API ab, die auf sichere Kontexte beschränkt ist. Einfache lokale Netzwerk-HTTP-URLs (z. B. http://192.168.x.x) funktionieren nicht.
  • Für Serverless- oder Edge-Deployments – der Standard-Wiederholungsschutz nutzt prozesslokalen Speicher, der nicht zwischen Serverless-Instanzen geteilt wird. Setze replayPrevention: 'remote' mit einem atomaren verteilten Store, um Replay-Angriffe in diesen Umgebungen zu verhindern.