Cloudflare Turnstile Skill

CAPTCHA-Alternative Bot Protection for Cloudflare Workers, React, Next.js, and Hono

Status: Production Ready ✅ Last Updated: 2025-10-22 Production Tested: @marsidev/react-turnstile (Cloudflare-verified), Official Workers examples

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• turnstile
• cloudflare turnstile
• cf-turnstile
• turnstile widget
• siteverify
• captcha alternative
• bot protection
• spam prevention

Secondary Keywords

• form protection
• login security
• signup bot protection
• recaptcha migration
• recaptcha alternative
• hcaptcha alternative
• invisible captcha
• managed challenge
• @marsidev/react-turnstile
• turnstile react
• turnstile next.js
• turnstile hono
• turnstile workers
• turnstile validation
• turnstile server-side

Error-Based Keywords

• error 100
• error 110200
• error 200500
• error 300030
• error 600010
• turnstile error
• unknown domain
• turnstile csp
• content security policy turnstile
• turnstile token expired
• turnstile token invalid
• turnstile localhost
• turnstile safari
• turnstile brave
• turnstile jest
• challenge error

---

What This Skill Does

Provides comprehensive patterns for implementing Cloudflare Turnstile, the invisible CAPTCHA-alternative bot protection system. Includes client-side widget integration, mandatory server-side validation, error handling, testing strategies, and React/Next.js/Hono patterns. Prevents 12 documented issues including CSP blocks, token expiration, secret key exposure, and browser incompatibilities.

Core Capabilities

✅ Client-side widget integration (implicit & explicit rendering) ✅ Server-side Siteverify API validation (Cloudflare Workers, Hono) ✅ React/Next.js integration with @marsidev/react-turnstile ✅ E2E testing patterns with dummy sitekeys (Playwright, Cypress, Jest) ✅ Complete error code reference with troubleshooting (100*, 200*, 300*, 400*, 600*) ✅ CSP configuration guidance and validation script ✅ Token lifecycle management (expiration, retry, refresh) ✅ Migration from reCAPTCHA/hCaptcha

---

Known Issues This Skill Prevents

---

When to Use This Skill

✅ Use When:

• Adding bot protection to forms (login, signup, contact, etc.)
• Migrating from reCAPTCHA or hCaptcha to Turnstile
• Implementing server-side token validation in Cloudflare Workers
• Integrating Turnstile with React, Next.js, or Hono applications
• Debugging Turnstile error codes (100*, 200*, 300*, 400*, 600*)
• Setting up E2E tests with Turnstile (Playwright, Cypress, Jest)
• Configuring CSP for Turnstile compatibility
• Handling token expiration or validation failures
• Implementing retry logic for transient errors

❌ Don't Use When:

• Building Cloudflare WAF rules (separate concern)
• Implementing Cloudflare Bot Management (enterprise feature, different system)
• Setting up Cloudflare Challenge Pages (different from Turnstile widgets)
• Building general form validation (Turnstile is specifically for bot protection)

---

Quick Usage Example

<!-- Client-Side (HTML) -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form action="/submit" method="POST">
  <input type="email" name="email" required>
  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
  <button type="submit">Submit</button>
</form>

// Server-Side (Cloudflare Workers)
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const formData = await request.formData()
    const token = formData.get('cf-turnstile-response')

    // Validate token (MANDATORY)
    const verifyFormData = new FormData()
    verifyFormData.append('secret', env.TURNSTILE_SECRET_KEY)
    verifyFormData.append('response', token)

    const result = await fetch(
      'https://challenges.cloudflare.com/turnstile/v0/siteverify',
      { method: 'POST', body: verifyFormData }
    )

    const outcome = await result.json()
    if (!outcome.success) {
      return new Response('Invalid token', { status: 401 })
    }

    // Process form
    return new Response('Success!')
  }
}

Result: Invisible bot protection with server-side validation

Full instructions: See SKILL.md

---

Token Efficiency Metrics

---

Package Versions (Verified 2025-10-22)

---

Dependencies

Prerequisites: None (optional: cloudflare-worker-base skill for Workers setup)

Integrates With:

• cloudflare-worker-base (Workers + Vite + Static Assets)
• hono-routing (Hono API patterns)
• tailwind-v4-shadcn (UI components)
• react-hook-form-zod (Form validation)

---

File Structure

cloudflare-turnstile/
├── SKILL.md                          # Complete documentation
├── README.md                         # This file
├── templates/                        # 7 ready-to-use templates
│   ├── wrangler-turnstile-config.jsonc
│   ├── turnstile-widget-implicit.html
│   ├── turnstile-widget-explicit.ts
│   ├── turnstile-server-validation.ts
│   ├── turnstile-react-component.tsx
│   ├── turnstile-hono-route.ts
│   └── turnstile-test-config.ts
├── references/                       # 4 reference docs
│   ├── widget-configs.md
│   ├── error-codes.md
│   ├── testing-guide.md
│   └── react-integration.md
└── scripts/                          # CSP verification
    └── check-csp.sh

---

Official Documentation

• Cloudflare Turnstile: https://developers.cloudflare.com/turnstile/
• Get Started Guide: https://developers.cloudflare.com/turnstile/get-started/
• Error Codes: https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/
• Community Resources: https://developers.cloudflare.com/turnstile/community-resources/
• Context7 Library: N/A (uses official Cloudflare Docs MCP)

---

Related Skills

• cloudflare-worker-base - Hono + Vite + Workers foundation
• hono-routing - Hono API routing patterns
• react-hook-form-zod - Form validation with Zod schemas
• tailwind-v4-shadcn - UI components and styling

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/jezweb/claude-skills/issues
• Email: jeremy@jezweb.net
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: @marsidev/react-turnstile (Cloudflare-verified) Token Savings: ~65-70% Error Prevention: 100% (12 documented issues) Ready to use! See SKILL.md for complete setup.