TrustComponent
Next.js
TrustCaptcha · Bot-Schutz

Next.js CAPTCHA-Integration

Binde ein Next.js-CAPTCHA mit wenigen Zeilen TypeScript in einen Route Handler oder eine Server Action ein. Unser React-Widget läuft im Client, die Prüfung auf deinem Server, und Bot-Spam bleibt aus Logins, Registrierungen und Kontaktformularen draußen. EU-gehostet, DSGVO-konform und ohne Bilderrätsel.

Schnellstart

So funktioniert die Integration

1. CAPTCHA erstellen

Erstelle ein Benutzerkonto oder melde dich mit einem bestehenden Konto an. Dann erstellst du ein neues CAPTCHA oder wählst ein vorhandenes aus. Wenn du TrustCaptcha erst ausprobieren willst: Jeder Tarif startet mit einer 14-tägigen kostenlosen Testphase.

Auf der Übersichtsseite des CAPTCHAs findest du den Site Key und den License Key, und dort erstellst du auch deinen API-Key. Trage die Domains deiner Website in den Sicherheitsregeln des CAPTCHAs als autorisierte Domains ein, damit sie dein CAPTCHA nutzen dürfen.

Start des Formulars zur Erstellung eines CAPTCHA.
CAPTCHA-Sicherheitsregeln eines Demo-CAPTCHAs.

2. CAPTCHA-Widget in deine Form-Komponente einbauen

Nutze unseren React-Wrapper in der Client Component, die dein Formular rendert. Das Widget läuft im Hintergrund und fügt beim Absenden ein verstecktes Feld tc-verification-token hinzu, das Server Actions und Route Handler als Form Data erhalten.

Installiere zunächst unser TrustCaptcha-React-Paket:

Install
bash
npm i @trustcomponent/trustcaptcha-react

Setze dann die <TrustcaptchaComponent> in die Client Component, die dein Formular rendert:

app/contact/contact-form.tsx
TypeScript
"use client";

import { TrustcaptchaComponent } from "@trustcomponent/trustcaptcha-react";

export function ContactForm() {
  return (
    <form method="post" action="/api/contact">
      <input type="email" name="email" required />
      <TrustcaptchaComponent sitekey="<your_site_key>" />
      <button type="submit">Send</button>
    </form>
  );
}

Das CAPTCHA-Widget wird anschließend in deinem Formular angezeigt:

CAPTCHA-Widget vor dem Start

Detaillierte Informationen zur CAPTCHA-React-Widget-Integration?
Die vollständige Widget-Referenz mit Themes, Sprachen, eigenem Design und mehr findest du in unserer Dokumentation.

Dokumentation lesen

3. Token in einem Route Handler oder einer Server Action validieren

Hole in einem Next.js-Route-Handler (oder einer Server Action) den Verifikationstoken aus den Form-Daten, rufe das Ergebnis über unsere Node.js-Library ab und entscheide, ob die Anfrage akzeptiert werden soll.

Installiere zunächst unsere TrustCaptcha-Node.js-Library:

Install
bash
npm i @trustcomponent/trustcaptcha-nodejs

Validiere dann den Token in deinem Route Handler und reagiere auf das Ergebnis:

app/api/contact/route.ts
TypeScript
import { NextResponse } from "next/server";
import { TrustCaptcha } from "@trustcomponent/trustcaptcha-nodejs";

export async function POST(request: Request) {
  const formData = await request.formData();
  const token = String(formData.get("tc-verification-token") ?? "");

  try {
    const result = await TrustCaptcha.getVerificationResult(process.env.TRUSTCAPTCHA_API_KEY!, token);
    if (!result.verificationPassed || result.score > 0.5) {
      return NextResponse.json({ error: "CAPTCHA verification failed." }, { status: 400 });
    }
  } catch {
    return NextResponse.json({ error: "CAPTCHA verification failed." }, { status: 400 });
  }

  // CAPTCHA bestanden — Anfrage verarbeiten
  return NextResponse.json({ status: "ok" });
}

Detaillierte Informationen zur Next.js-CAPTCHA-Integration?
Die vollständige Schritt-für-Schritt-Anleitung, inklusive einer Server-Action-Variante und eines wiederverwendbaren Verifier-Utilities, findest du in unserer Dokumentation.

Dokumentation lesen

Anderes Backend-Framework statt Next.js?
Wenn du ein anderes Framework nutzt, wähle hier das passende Rezept aus. Ist dein Framework nicht aufgeführt, können deine Softwareentwickler die Verifizierung mithilfe unserer Dokumentation selbst integrieren oder unser Support-Team nach einer vorgefertigten Integration fragen.

Actix Web
ASP.NET Core
Axum
Django
Echo
Express
FastAPI
Fastify
Fiber
Flask
Gin
Hapi
Laravel
Micronaut
NestJS
Next.js
Quarkus
Ruby on Rails
Sinatra
Spring Boot
Symfony

4. Integration testen

TrustCaptcha ist jetzt aktiv. Schick eine Testanfrage ab und prüfe, ob sie durchgeht.

CAPTCHA abgeschlossen

Häufige Fragen

Funktioniert das Next.js-CAPTCHA mit App Router und Pages Router?
Ja, beides. Im App Router validierst du den Token typischerweise in einem Route Handler (app/api/.../route.ts) oder einer Server Action. Im Pages Router machst du dasselbe in einer API-Route (pages/api/...). Der SDK-Aufruf ist identisch.
Kann ich das CAPTCHA aus einer Server Action heraus prüfen?
Ja, und das passt sehr gut. Lies den Token aus den FormData, die in deine "use server"-Action gereicht werden, rufe unsere Node.js-Library auf und gib bei Fehlschlag einen Fehler zurück. Das CAPTCHA bleibt vollständig serverseitig, und deine Client Component sieht den API-Key nie.
Funktioniert das React-Widget in einer Server Component?
Das Widget läuft im Browser, rendere es daher aus einer Client Component ("use client"). Das Formular kann trotzdem an eine Server Action oder einen Route Handler abgesendet werden. Die Verifizierung passiert komplett serverseitig.
Kann ich die CAPTCHA-Verifizierung in der Edge Runtime laufen lassen?
Nein. Unsere Node.js-Library nutzt Node-spezifische APIs (axios). Setze die Runtime auf Routen, die CAPTCHA-Tokens prüfen, auf "nodejs". Die Default-Runtime in Next.js ist bereits "nodejs". Du musst nur eingreifen, wenn du runtime = "edge" explizit gesetzt hast.
Wo speichere ich den CAPTCHA-API-Key in einem Next.js-Projekt?
In .env.local während der Entwicklung und in den Environment Variables deines Hosting-Providers (Vercel, Netlify, …) in Produktion. Lies ihn über process.env.TRUSTCAPTCHA_API_KEY innerhalb von Server-Code und exponiere ihn niemals über NEXT_PUBLIC_*.
Wie halte ich das CAPTCHA-Verifizierungs-Utility aus dem Client-Bundle heraus?
Füge import "server-only" am Anfang der Datei hinzu, die unsere Node.js-Library importiert. Damit lässt Next.js den Build fehlschlagen, sobald die Datei in eine Client Component gelangt. Das verhindert, dass der API-Key versehentlich an den Browser ausgeliefert wird.
Leads verlieren wegen CAPTCHAs?

TrustCaptcha blockiert Spam und Bots, nicht deine Kunden. Keine Rätsel, DSGVO-konform, in der EU gehostet.

CAPTCHA-Start
CAPTCHA abgeschlossen
Keine Rätsel für Besucher
Die Prüfung läuft im Hintergrund, während Besucher tippen. So schicken mehr Menschen deine Formulare ab, statt vorher aufzugeben.
DSGVO-konform
In der EU gehostet, ohne Cookies, mit verschlüsselter Übertragung und automatischer Löschung. Jeder Kunde bekommt einen Auftragsverarbeitungsvertrag (AVV).
Mehrstufige Sicherheit
Adaptiver Proof-of-Work und Risiko-Scoring stoppen Missbrauch früh, auch wenn der Angriffs-Traffic plötzlich steigt.
Volle Kontrolle
Stell die Empfindlichkeit ein, pflege Allow- und Blocklisten und nutze Geoblocking. Du entscheidest, wie streng die Prüfung ist.

Schütze deine Next.js-Anwendung in wenigen Schritten mit TrustCaptcha!

  • EU-hosted & DSGVO-konform
  • Keine Rätsel
  • 14 Tage kostenlos testen