Skip to content

secondsky/claude-skills / plugins/cloudflare-turnstile/skills/cloudflare-turnstile

cloudflare-turnstile

Verified

This skill should be used when the user asks to "add turnstile", "implement bot protection", "validate turnstile token", "fix turnstile error", "setup captcha alternative", or encounters error codes 100*/300*/600*, CSP errors, or token validation failures. Provides CAPTCHA-alternative protection for Cloudflare Workers, React, Next.js, and Hono.

references/react-integration.md

View on GitHub
# React Integration Guide

**Best practices for integrating Turnstile with React, Next.js, and modern React patterns**

**Recommended Package**: @marsidev/react-turnstile (Cloudflare-verified)

---

## Package Installation

```bash
npm install @marsidev/react-turnstile
# or
pnpm add @marsidev/react-turnstile
# or
yarn add @marsidev/react-turnstile
```

**Current Version**: 1.3.1 (September 2025)
**React Compatibility**: React 18+, Next.js 13+, 14+, 15+

---

## Basic Usage

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

export function ContactForm() {
  const [token, setToken] = useState<string>()

  return (
    <form>
      <input name="email" type="email" required />
      <textarea name="message" required />

      <Turnstile
        siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
        onSuccess={setToken}
      />

      <button disabled={!token}>Submit</button>
    </form>
  )
}
```

---

## Props Reference

### Required Props

#### `siteKey`
**Type**: `string`
**Description**: Your Turnstile sitekey

```tsx
<Turnstile siteKey="YOUR_SITE_KEY" />
```

### Optional Props

#### `onSuccess`
**Type**: `(token: string) => void`
**Description**: Called when challenge succeeds

```tsx
<Turnstile onSuccess={(token) => console.log(token)} />
```

#### `onError`
**Type**: `(error: string) => void`
**Description**: Called when challenge fails

```tsx
<Turnstile onError={(error) => console.error(error)} />
```

#### `onExpire`
**Type**: `() => void`
**Description**: Called when token expires (5 min)

```tsx
<Turnstile onExpire={() => setToken(undefined)} />
```

#### `onAbort`
**Type**: `() => void`
**Description**: Called when challenge is aborted

#### `options`
**Type**: `TurnstileOptions`
**Description**: Widget configuration

```tsx
<Turnstile
  siteKey="..."
  options={{
    theme: 'dark',
    size: 'compact',
    action: 'login',
  }}
/>
```

---

## Using Refs

Access widget instance for manual control:

```tsx
import { useRef } from 'react'
import { Turnstile, type TurnstileInstance } from '@marsidev/react-turnstile'

export function AdvancedForm() {
  const turnstileRef = useRef<TurnstileInstance>(null)

  function handleReset() {
    turnstileRef.current?.reset()
  }

  function handleRemove() {
    turnstileRef.current?.remove()
  }

  return (
    <>
      <Turnstile ref={turnstileRef} siteKey="..." />
      <button onClick={handleReset}>Reset</button>
      <button onClick={handleRemove}>Remove</button>
    </>
  )
}
```

---

## Next.js App Router

### Client Component

```tsx
// app/contact/page.tsx
'use client'

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

export default function ContactPage() {
  const [token, setToken] = useState<string>()

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()

    const formData = new FormData(e.currentTarget)

    const response = await fetch('/api/contact', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: formData.get('email'),
        message: formData.get('message'),
        'cf-turnstile-response': token,
      }),
    })

    if (response.ok) {
      alert('Success!')
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <textarea name="message" required />

      <Turnstile
        siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
        onSuccess={setToken}
        onExpire={() => setToken(undefined)}
      />

      <button disabled={!token}>Submit</button>
    </form>
  )
}
```

### Server Action (Next.js 14+)

```tsx
'use server'

import { validateTurnstile } from '@/lib/turnstile'

export async function submitContact(formData: FormData) {
  const token = formData.get('cf-turnstile-response')?.toString()

  if (!token) {
    return { error: 'Missing verification' }
  }

  const result = await validateTurnstile(token, process.env.TURNSTILE_SECRET_KEY!)

  if (!result.success) {
    return { error: 'Verification failed' }
  }

  // Process form
  return { success: true }
}
```

---

## Next.js Pages Router

### Page Component

```tsx
// pages/contact.tsx
import { Turnstile } from '@marsidev/react-turnstile'
import { useState } from 'react'

export default function ContactPage() {
  const [token, setToken] = useState<string>()

  return (
    <form>
      <Turnstile
        siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
        onSuccess={setToken}
      />
    </form>
  )
}
```

### API Route

```typescript
// pages/api/contact.ts
import type { NextApiRequest, NextApiResponse } from 'next'
import { validateTurnstile } from '@/lib/turnstile'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' })
  }

  const token = req.body['cf-turnstile-response']

  if (!token) {
    return res.status(400).json({ error: 'Missing token' })
  }

  const result = await validateTurnstile(
    token,
    process.env.TURNSTILE_SECRET_KEY!,
    {
      remoteip: req.headers['x-forwarded-for']?.toString() || req.socket.remoteAddress,
    }
  )

  if (!result.success) {
    return res.status(401).json({ error: 'Invalid token' })
  }

  // Process form
  res.status(200).json({ success: true })
}
```

---

## Custom Hook Pattern

```tsx
// hooks/useTurnstile.ts
import { useRef, useState } from 'react'
import { Turnstile, type TurnstileInstance } from '@marsidev/react-turnstile'

export function useTurnstile(siteKey: string) {
  const [token, setToken] = useState<string>()
  const [isReady, setIsReady] = useState(false)
  const [error, setError] = useState<string>()
  const turnstileRef = useRef<TurnstileInstance>(null)

  const reset = () => {
    turnstileRef.current?.reset()
    setToken(undefined)
    setIsReady(false)
    setError(undefined)
  }

  const TurnstileWidget = () => (
    <Turnstile
      ref={turnstileRef}
      siteKey={siteKey}
      onSuccess={(token) => {
        setToken(token)
        setIsReady(true)
        setError(undefined)
      }}
      onError={(err) => {
        setError(err)
        setIsReady(false)
      }}
      onExpire={() => {
        setToken(undefined)
        setIsReady(false)
      }}
    />
  )

  return {
    token,
    isReady,
    error,
    reset,
    TurnstileWidget,
  }
}

// Usage
export function MyForm() {
  const { token, isReady, error, reset, TurnstileWidget } = useTurnstile(
    process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!
  )

  return (
    <form>
      <TurnstileWidget />
      {error && <div>Error: {error}</div>}
      <button disabled={!isReady}>Submit</button>
    </form>
  )
}
```

---

## Jest Testing

### Mock Setup

```typescript
// jest.setup.ts
import React from 'react'

jest.mock('@marsidev/react-turnstile', () => ({
  Turnstile: ({ onSuccess }: { onSuccess: (token: string) => void }) => {
    React.useEffect(() => {
      onSuccess('XXXX.DUMMY.TOKEN.XXXX')
    }, [onSuccess])

    return <div data-testid="turnstile-mock" />
  },
}))
```

### Component Test

```tsx
// ContactForm.test.tsx
import { render, screen, fireEvent } from '@testing-library/react'
import { ContactForm } from './ContactForm'

test('submits form with Turnstile', async () => {
  render(<ContactForm />)

  const submitButton = screen.getByRole('button', { name: 'Submit' })

  // Turnstile auto-solves (mocked)
  await waitFor(() => {
    expect(submitButton).not.toBeDisabled()
  })

  fireEvent.click(submitButton)

  expect(await screen.findByText('Success')).toBeInTheDocument()
})
```

---

## Environment-Aware Sitekey

```tsx
// lib/turnstile.ts
export function useTurnstileSiteKey() {
  // Test/Development: Use dummy key
  if (process.env.NODE_ENV !== 'production') {
    return '1x00000000000000000000AA'
  }

  // Production: Use real key
  return process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!
}

// Usage
import { useTurnstileSiteKey } from '@/lib/turnstile'

export function MyForm() {
  const siteKey = useTurnstileSiteKey()

  return <Turnstile siteKey={siteKey} />
}
```

---

## Known Issues & Workarounds

### Issue #112: Next.js + Jest Compatibility (Oct 2025)

**Problem**: @marsidev/react-turnstile breaks Jest tests

**Source**: https://github.com/marsidev/react-turnstile/issues/112

**Workaround**: Mock the component (see Jest Testing section above)

### Issue #113: Blocked Script Execution (Oct 2025)

**Problem**: Script execution blocked in some environments

**Source**: https://github.com/marsidev/react-turnstile/issues/113

**Workaround**:
1. Check CSP headers allow `challenges.cloudflare.com`
2. Ensure `api.js` loads from CDN (not proxied)

---

## TypeScript Types

```typescript
import type {
  TurnstileInstance,
  TurnstileProps,
  TurnstileOptions,
} from '@marsidev/react-turnstile'

// Widget instance methods
interface TurnstileInstance {
  reset(): void
  remove(): void
  execute(): void
  getResponse(): string | undefined
  isExpired(): boolean
}

// Component props
interface TurnstileProps {
  siteKey: string
  onSuccess?: (token: string) => void
  onError?: (error: string) => void
  onExpire?: () => void
  onAbort?: () => void
  options?: TurnstileOptions
  scriptOptions?: {
    nonce?: string
    defer?: boolean
    async?: boolean
  }
}

// Widget options
interface TurnstileOptions {
  theme?: 'light' | 'dark' | 'auto'
  size?: 'normal' | 'compact' | 'flexible'
  action?: string
  cdata?: string
  execution?: 'render' | 'execute'
  appearance?: 'always' | 'execute' | 'interaction-only'
  retry?: 'auto' | 'never'
  'retry-interval'?: number
}
```

---

## Performance Optimization

### Lazy Loading

```tsx
import { lazy, Suspense } from 'react'

const Turnstile = lazy(() =>
  import('@marsidev/react-turnstile').then(mod => ({ default: mod.Turnstile }))
)

export function LazyTurnstileForm() {
  return (
    <form>
      <Suspense fallback={<div>Loading verification...</div>}>
        <Turnstile siteKey="..." />
      </Suspense>
    </form>
  )
}
```

### Conditional Rendering

Only render Turnstile when needed:

```tsx
export function ConditionalForm() {
  const [showTurnstile, setShowTurnstile] = useState(false)

  return (
    <form>
      <input onChange={() => setShowTurnstile(true)} />

      {showTurnstile && <Turnstile siteKey="..." />}
    </form>
  )
}
```

---

## Best Practices

✅ **Use environment variables** for sitekeys
✅ **Mock in tests** using Jest setup file
✅ **Handle expiration** with `onExpire` callback
✅ **Disable submit until ready** based on token state
✅ **Reset after submission** for multi-use forms
✅ **Use TypeScript** for type safety
✅ **Lazy load** if not immediately needed

❌ **Don't hardcode sitekeys** in components
❌ **Don't skip error handling** (`onError`)
❌ **Don't forget server validation** (critical!)
❌ **Don't use production keys in tests**

---

**Last Updated**: 2025-10-22
**Package Version**: @marsidev/react-turnstile@1.3.1
**Cloudflare Status**: ✅ Officially Recommended
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall