VanTurnstile

Turnstile wrapper for the VanJS ecosystem with a handle-first API:

• Browser-first TypeScript package
• Cloudflare script loading with deduplication
• Reactive token state via van.state
• Imperative widget controls: reset, execute, getResponse, remove, dispose

Install

bun add van-turnstile vanjs-core

Or with npm:

npm install van-turnstile vanjs-core

Usage

import van from "vanjs-core";
import { Turnstile } from "van-turnstile";

const captcha = Turnstile({
  sitekey: "your-site-key",
  onToken: (token) => {
    console.log("token:", token);
  },
  onTokenExpired: () => {
    console.log("expired");
  },
  onError: (code) => {
    console.error("turnstile error:", code);
  }
});

const target = document.querySelector("#app");
if (target) {
  van.add(target, captcha.el);
}

API

Turnstile(props: TurnstileProps): TurnstileHandle

TurnstileProps:

• sitekey: string (required)
• onToken?: (token: string) => void
• onTokenExpired?: () => void
• onError?: (errorCode?: string) => void
• autoRefresh?: boolean (default true)
• theme?: "auto" | "light" | "dark" (default auto)
• size?: "normal" | "compact" | "flexible" (default normal)
• appearance?: "always" | "execute" | "interaction-only"
• execution?: "render" | "execute" (default render)
• action?: string
• cData?: string
• class?: string

TurnstileHandle:

• el: HTMLDivElement
• token: State<string | null>
• reset(): void
• remove(): void
• execute(): void
• getResponse(): string | null
• dispose(): void

Demo

This repository includes a Vite demo that showcases:

• widget configuration (theme, size, appearance, execution, action, cData)
• token and event state updates
• imperative methods and remount flow

Run it locally:

bun install
bun run demo

Build the demo:

bun run demo:build

Development

bun run test
bun run build
bun run lint
bun run check

Notes

• Browser-only package in v1.
• Turnstile token verification must happen on your server in production.
• Backend verification helpers are intentionally out of scope for this package.