/setup-wizard

name: cloudflare-turnstile:setup
description: Interactive wizard for setting up Cloudflare Turnstile. Generates templates, configuration, and provides step-by-step guidance based on framework and environment.

Turnstile Setup Wizard

This interactive command guides you through complete Cloudflare Turnstile setup, from widget configuration to server-side validation.

Usage

/turnstile-setup

---

Step 1: Widget Mode Selection

**Question**: "What widget mode do you need?"

**Options**:

1. **Managed (Recommended)** - Shows checkbox only when bot suspected

• Best balance of security and UX
• Use for: Login pages, contact forms, user-facing challenges
• Solve rate: ~95% pass without interaction

2. **Invisible** - No visible widget, challenge runs in background

• Best for: API protection, seamless UX, checkout flows
• No user interaction required
• Execute programmatically via `turnstile.execute()`

3. **Non-Interactive** - Widget visible but no interaction needed

• Similar to invisible but shows "Verifying..." state
• Use for: Status transparency, compliance requirements

**Output**: Store selection as `WIDGET_MODE`

---

Step 2: Framework Selection

**Question**: "What framework are you using?"

**Options**:

1. **Cloudflare Workers (Hono)**

• Template: `templates/turnstile-hono-route.ts`
• Config: `templates/wrangler-turnstile-config.jsonc`
• Server validation with Hono middleware

2. **React / Next.js**

• Template: `templates/turnstile-react-component.tsx`
• Package: `@marsidev/react-turnstile@1.3.1`
• Client + server validation

3. **Vanilla HTML/JavaScript**

• Template: `templates/turnstile-widget-implicit.html` (implicit rendering)
• Template: `templates/turnstile-widget-explicit.ts` (explicit rendering)
• Framework-agnostic setup

4. **Mobile (iOS/Android/React Native/Flutter)**

• Reference: `references/mobile-implementation.md`
• WebView integration required
• Platform-specific configuration

**Output**: Store selection as `FRAMEWORK`

---

Step 3: Environment Selection

**Question**: "What environment is this for?"

**Options**:

1. **Development (localhost)**

• Use dummy test sitekey: `1x00000000000000000000AA`
• Use dummy test secret: `1x0000000000000000000000000000000AA`
• Always passes validation (for testing)
• No domain configuration needed

2. **Staging**

• Create staging-specific widget in Cloudflare Dashboard
• Configure staging domain in allowed domains
• Use separate sitekey/secret from production

3. **Production**

• Create production widget in Cloudflare Dashboard
• Configure production domain(s) in allowed domains
• Rotate secret keys periodically
• Monitor analytics dashboard

**Output**: Store selection as `ENVIRONMENT`

---

Step 4: Generate Configuration

Based on selections (`WIDGET_MODE`, `FRAMEWORK`, `ENVIRONMENT`), generate appropriate files:

For Cloudflare Workers (Hono)

**Generate `wrangler.jsonc`**:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-15",
  "vars": {
    "TURNSTILE_SITE_KEY": "${ENVIRONMENT === 'development' ? '1x00000000000000000000AA' : 'YOUR_SITE_KEY'}"
  },
  "env": {
    "production": {
      "vars": {
        "TURNSTILE_SITE_KEY": "YOUR_PRODUCTION_SITE_KEY"
      }
    }
  }
}

**Generate Hono route** (from `templates/turnstile-hono-route.ts`):

import { Hono } from 'hono'

const app = new Hono<{ Bindings: Env }>()

app.post('/api/verify', async (c) => {
  const { token } = await c.req.json()

  // Validate token with Turnstile Siteverify API
  const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      secret: c.env.TURNSTILE_SECRET_KEY,
      response: token,
    }),
  })

  const outcome = await result.json()

  if (!outcome.success) {
    return c.json({ error: 'Validation failed' }, 401)
  }

  return c.json({ success: true })
})

For React / Next.js

**Generate React component** (from `templates/turnstile-react-component.tsx`):

'use client'

import { Turnstile } from '@marsidev/react-turnstile'
import { useState } from 'react'

export function TurnstileWidget() {
  const [token, setToken] = useState('')

  return (
    <Turnstile
      siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
      onSuccess={setToken}
      options={{
        theme: 'auto',
        size: 'normal',
        execution: '${WIDGET_MODE === 'Invisible' ? 'execute' : 'render'}',
      }}
    />
  )
}

**Add package.json dependency**:

npm install @marsidev/react-turnstile@1.3.1

For Vanilla HTML/JavaScript

**Generate HTML** (from `templates/turnstile-widget-implicit.html`):

<!DOCTYPE html>
<html>
<head>
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
  <form id="myForm" method="POST" action="/submit">
    <!-- Turnstile widget (implicit rendering) -->
    <div class="cf-turnstile"
         data-sitekey="${ENVIRONMENT === 'development' ? '1x00000000000000000000AA' : 'YOUR_SITE_KEY'}"
         data-callback="onTurnstileSuccess"
         data-theme="auto"
         data-size="normal">
    </div>

    <button type="submit">Submit</button>
  </form>

  <script>
    function onTurnstileSuccess(token) {
      console.log('Turnstile token:', token)
      // Form will auto-submit with cf-turnstile-response hidden input
    }
  </script>
</body>
</html>

---

Step 5: Cloudflare Dashboard Setup

**Provide instructions for dashboard configuration**:

5.1: Create Widget

1. Go to https://dash.cloudflare.com/?to=/:account/turnstile 2. Click "Add Site" or "Add Widget" 3. Configure widget:

• **Site Name**: `${PROJECT_NAME}-${ENVIRONMENT}`
• **Domain**: Add your domain (e.g., `example.com`, `localhost` for dev)
• **Widget Mode**