@truesift/next

Official TrueSift SDK for Next.js App Router projects.

@truesift/next adds TrueSift human verification to Next.js applications through a ready-to-use client component and secure server-side route helpers. It is designed for forms, contact pages, checkout flows, lead forms, and other public actions where you want a privacy-first verification layer without exposing your secret key in the browser.

Current Version

0.1.2

Features

• Next.js App Router support.
• Secure server-side challenge and verification handlers.
• Client-side TrueSiftCheck verification component.
• Compact, responsive, and adaptive visual layouts.
• Light, dark, and automatic theme support.
• Built-in English, German, and Bulgarian UI labels.
• Custom label overrides for product-specific copy.
• Bundled visual verification animation with SVG fallback.
• Keeps the TrueSift secret key on the server.

Installation

pnpm add @truesift/next

or:

npm install @truesift/next

Public Entry Points

Use the client component from the client entry point:

import { TrueSiftCheck } from "@truesift/next/client";

Use the server route helpers from the server entry point:

import {
  createTrueSiftChallengeHandler,
  createTrueSiftVerifyHandler
} from "@truesift/next/server";

Do not import server helpers into client components.

Environment Variables

Add the TrueSift configuration to your server-side environment:

TRUESIFT_API_BASE_URL=https://truesift.webdigitech.de
TRUESIFT_SITE_KEY=bg_site_...
TRUESIFT_SECRET_KEY=...
TRUESIFT_DEFAULT_ACTION=website_check
TRUESIFT_FAIL_OPEN=true
TRUESIFT_TIMEOUT_MS=2500

TRUESIFT_API_BASE_URL should contain only the TrueSift service origin.

Correct:

TRUESIFT_API_BASE_URL=https://truesift.webdigitech.de

Do not append paths such as /api/v1, /challenge, or /verify.

Never expose the secret key through public environment variables. Do not create variables such as:

NEXT_PUBLIC_TRUESIFT_SECRET_KEY=...

Next.js App Router Setup

Create two local API routes in your Next.js app:

src/app/api/truesift/challenge/route.ts
src/app/api/truesift/verify/route.ts

Challenge Route

import { createTrueSiftChallengeHandler } from "@truesift/next/server";

export const dynamic = "force-dynamic";
export const runtime = "nodejs";

export const POST = createTrueSiftChallengeHandler({
  apiBaseUrl: process.env.TRUESIFT_API_BASE_URL,
  siteKey: process.env.TRUESIFT_SITE_KEY,
  secretKey: process.env.TRUESIFT_SECRET_KEY,
  defaultAction: process.env.TRUESIFT_DEFAULT_ACTION,
  failOpen: process.env.TRUESIFT_FAIL_OPEN === "true",
  timeoutMs: Number(process.env.TRUESIFT_TIMEOUT_MS ?? 2500)
});

Verify Route

import { createTrueSiftVerifyHandler } from "@truesift/next/server";

export const dynamic = "force-dynamic";
export const runtime = "nodejs";

export const POST = createTrueSiftVerifyHandler({
  apiBaseUrl: process.env.TRUESIFT_API_BASE_URL,
  siteKey: process.env.TRUESIFT_SITE_KEY,
  secretKey: process.env.TRUESIFT_SECRET_KEY,
  defaultAction: process.env.TRUESIFT_DEFAULT_ACTION,
  failOpen: process.env.TRUESIFT_FAIL_OPEN === "true",
  timeoutMs: Number(process.env.TRUESIFT_TIMEOUT_MS ?? 2500)
});

Basic Client Usage

"use client";

import { TrueSiftCheck } from "@truesift/next/client";

export function ContactSecurityCheck() {
  return (
    <TrueSiftCheck
      action="contact_form"
      path="/contact"
      challengeUrl="/api/truesift/challenge"
      verifyUrl="/api/truesift/verify"
      onVerified={(result) => {
        console.info("TrueSift verification completed.", result);
      }}
      onError={(error) => {
        console.warn("TrueSift verification failed.", error);
      }}
    />
  );
}

Default local API paths:

/api/truesift/challenge
/api/truesift/verify

Visual Layouts

TrueSiftCheck supports several layouts for different UI placements.

<TrueSiftCheck
  action="contact_form"
  path="/contact"
  visualMode="checkbox"
  size="compact"
  theme="auto"
  locale="de"
/>

Available visual modes:

| Mode | Best for | | --- | --- | | checkbox | Forms, checkout areas, compact verification blocks | | banner | Wider landing page sections or prominent verification areas | | inline | Inline UI placements inside existing layouts | | badge | Small status-style verification indicators |

Available sizes:

| Size | Description | | --- | --- | | normal | Default balanced size | | compact | Smaller layout for tight spaces | | flexible | Adapts to the available container width |

Available themes:

| Theme | Description | | --- | --- | | auto | Uses the surrounding environment where possible | | light | Light interface | | dark | Dark interface |

Localization

The component includes built-in labels for:

• English: en
• German: de
• Bulgarian: bg
• Automatic detection: auto

Example:

<TrueSiftCheck
  action="contact_form"
  locale="de"
/>

You can also override labels manually:

<TrueSiftCheck
  action="contact_form"
  labels={{
    idle: "Bitte bestätigen Sie, dass Sie ein Mensch sind.",
    checking: "Prüfung läuft …",
    verified: "Prüfung abgeschlossen.",
    failed: "Bitte versuchen Sie es erneut.",
    unavailable: "Prüfung derzeit nicht verfügbar.",
    meta: "Datenschutzfreundliche Verifizierung",
    retry: "Erneut versuchen",
    checkboxLabel: "Menschliche Interaktion bestätigen"
  }}
/>

The public attribution line Made in 🇩🇪 by WebDigiTech.de is part of the TrueSift visual identity and is not translated.

Client Props

| Prop | Type | Description | | --- | --- | --- | | action | string | Public action name, such as contact_form or checkout | | path | string | Page or route where the verification is used | | origin | string | Optional origin override | | challengeUrl | string | Local challenge API route | | verifyUrl | string | Local verify API route | | autoStart | boolean | Starts verification automatically when the component is ready | | disabled | boolean | Disables the verification component | | className | string | Optional custom class name | | visualMode | "checkbox" \| "banner" \| "inline" \| "badge" | Visual layout mode | | size | "normal" \| "compact" \| "flexible" | Visual size behavior | | theme | "auto" \| "light" \| "dark" | Visual theme | | locale | "auto" \| "en" \| "de" \| "bg" | UI language | | labels | TrueSiftCheckLabels | Optional public UI label overrides | | lottie | TrueSiftCheckLottieConfig | Optional animation configuration | | onReady | () => void | Called when the component is ready | | onVerified | (result) => void | Called after verification completes | | onError | (error) => void | Called when verification fails |

Animation

The default TrueSift visual animation is bundled with the package and works out of the box.

You only need to provide a custom animation if your project intentionally wants to replace the default TrueSift visual.

<TrueSiftCheck
  action="contact_form"
  lottie={{
    enabled: true,
    fallback: "svg"
  }}
/>

The component includes a fallback SVG so verification can still be displayed when animation loading is unavailable or reduced motion is preferred.

Fail-Open Behavior

When failOpen is enabled on the server route helper, the application can continue when the TrueSift service is temporarily unavailable. This is useful for contact forms and lead forms where blocking real users during a temporary outage would be worse than allowing the request.

For high-risk actions, configure your TrueSift site and application flow according to your security requirements.

Security Notes

• Keep TRUESIFT_SECRET_KEY server-side only.
• Do not expose the secret key through NEXT_PUBLIC_* variables.
• Use local Next.js API routes for challenge and verification.
• Use clear action names so verification events are easy to understand later.
• Keep public UI messages calm and user-friendly.

License

Source code and package implementation:

MIT License.
See LICENSE.

Third-party animation asset:

Author: Maxence Chanel
License: Free to use under the Lottie Simple License
Usage: bundled visual asset for TrueSift verification states

The third-party animation asset is not authored by WebDigiTech and is not licensed under the MIT License by WebDigiTech. Its use remains subject to the terms of the Lottie Simple License and the original asset licensing conditions.