, })) // Option 2: transformIgnorePatterns in jest.config.js module.exports = { transformIgnorePatterns: [ 'node_modules/(?!(@marsidev/react-turnstile)/)' ] } // Option 3 (Recommended): Migrate to Vitest // Vitest handles ESM modules correctly without mocking ``` **Status**: Maintainer closed issue as "not planned". Recommend migrating to Vitest for new projects. ## Configuration **wrangler.jsonc:** ```jsonc { "vars": { "TURNSTILE_SITE_KEY": "1x00000000000000000000AA" }, "secrets": ["TURNSTILE_SECRET_KEY"] // Run: wrangler secret put TURNSTILE_SECRET_KEY } ``` **Required CSP:** ```html ``` --- ## Common Patterns ### Pattern 1: Hono + Cloudflare Workers ```typescript import { Hono } from 'hono' type Bindings = { TURNSTILE_SECRET_KEY: string TURNSTILE_SITE_KEY: string } const app = new Hono<{ Bindings: Bindings }>() app.post('/api/login', async (c) => { const body = await c.req.formData() const token = body.get('cf-turnstile-response') if (!token) { return c.text('Missing Turnstile token', 400) } // Validate token const verifyFormData = new FormData() verifyFormData.append('secret', c.env.TURNSTILE_SECRET_KEY) verifyFormData.append('response', token.toString()) verifyFormData.append('remoteip', c.req.header('CF-Connecting-IP') || '') // CRITICAL - always pass client IP const verifyResult = await fetch( 'https://challenges.cloudflare.com/turnstile/v0/siteverify', { method: 'POST', body: verifyFormData, } ) const outcome = await verifyResult.json<{ success: boolean }>() if (!outcome.success) { return c.text('Invalid Turnstile token', 401) } // Process login return c.json({ message: 'Login successful' }) }) export default app ``` **When to use**: API routes in Cloudflare Workers with Hono framework ### Pattern 2: React + Next.js App Router ```tsx 'use client' import { Turnstile } from '@marsidev/react-turnstile' import { useState } from 'react' export function ContactForm() { const [token, setToken] = useState() const [error, setError] = useState() async function handleSubmit(e: React.FormEvent) { e.preventDefault() if (!token) { setError('Please complete the challenge') return } const formData = new FormData(e.currentTarget) formData.append('cf-turnstile-response', token) const response = await fetch('/api/contact', { method: 'POST', body: formData, }) if (!response.ok) { setError('Submission failed') return } // Success } return (

<Turnstile
        siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY!}
        onSuccess={setToken}
        onError={() => setError('Challenge failed')}
        onExpire={() => setToken(undefined)}
      />

{error && <div className="error">{error}</div>}

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

**When to use**: Client-side forms in Next.js with React hooks

---

## Testing Keys

**Dummy Sitekeys (client):**
- Always pass: `1x00000000000000000000AA`
- Always block: `2x00000000000000000000AB`
- Force interactive: `3x00000000000000000000FF`

**Dummy Secret Keys (server):**
- Always pass: `1x0000000000000000000000000000000AA`
- Always fail: `2x0000000000000000000000000000000AA`
- Token already spent: `3x0000000000000000000000000000000AA`

---

## Bundled Resources

**Scripts:** `check-csp.sh` - Verify CSP allows Turnstile

**References:**
- `widget-configs.md` - All configuration options
- `error-codes.md` - Error code troubleshooting (100*/200*/300*/400*/600*)
- `testing-guide.md` - Testing strategies, dummy keys
- `react-integration.md` - React/Next.js patterns

**Templates:** Complete examples for Hono, React, implicit/explicit rendering, validation

---

## Advanced Features

**Pre-Clearance (SPAs):** Issue cookie that persists across page navigations
```typescript
turnstile.render('#container', {
  sitekey: SITE_KEY,
  callback: async (token) => {
    await fetch('/api/pre-clearance', { method: 'POST', body: JSON.stringify({ token }) })
  }
})
```

**Custom Actions & Data:** Track challenge types, pass custom data (max 255 chars)
```typescript
turnstile.render('#container', {
  action: 'login',  // Track in analytics
  cdata: JSON.stringify({ userId: '123' }),  // Custom payload
})
```

**Error Handling:** Use `retry: 'auto'` and `error-callback` for resilience
```typescript
turnstile.render('#container', {
  retry: 'auto',
  'retry-interval': 8000,  // ms between retries
  'error-callback': (error) => { /* handle or show fallback */ }
})
```

---

## Dependencies

**Required:** None (loads from CDN)
**React:** @marsidev/react-turnstile@1.4.1 (Cloudflare-recommended), turnstile-types@1.2.3
**Other:** vue-turnstile, ngx-turnstile, svelte-turnstile, @nuxtjs/turnstile

---

## Official Documentation

- https://developers.cloudflare.com/turnstile/
- Use `mcp__cloudflare-docs__search_cloudflare_documentation` tool

---

## Troubleshooting

### Problem: Error 110200 - "Unknown domain"
**Solution**: Add your domain (including localhost for dev) to widget's allowed domains in Cloudflare Dashboard. For local dev, use dummy test sitekey `1x00000000000000000000AA` instead.

### Problem: Error 300030 - Widget crashes for legitimate users
**Solution**: Implement error callback with retry logic. This is a known Cloudflare-side issue (2025). Fallback to alternative verification if retries fail.

### Problem: Tokens always return `success: false`
**Solution**:
1. Check token hasn't expired (5 min TTL)
2. Verify secret key is correct
3. Ensure token hasn't been validated before (single-use)
4. Check hostname matches widget configuration

### Problem: CSP blocking iframe (Error 200500)
**Solution**: Add CSP directives:
```html
<meta http-equiv="Content-Security-Policy" content="
  frame-src https://challenges.cloudflare.com;
  script-src https://challenges.cloudflare.com;
">
```

### Problem: Safari 18 "Hide IP" causing Error 300010
**Solution**: Document in error message that users should disable Safari's "Hide IP address" setting (Safari → Settings → Privacy → Hide IP address → Off)

### Problem: Next.js + Jest tests failing with @marsidev/react-turnstile
**Solution**: Mock the Turnstile component in Jest setup (or migrate to Vitest, which handles ESM modules correctly):
```typescript
// Option 1: Jest mocking (jest.setup.ts)
jest.mock('@marsidev/react-turnstile', () => ({
  Turnstile: () => <div data-testid="turnstile-mock" />,
}))

// Option 2: Migrate to Vitest (recommended for new projects)
// Vitest handles ESM modules without mocking required
```

**Note**: This issue persists in Jest 30.2.0 (Dec 2025). Maintainer closed as "not planned". See Issue #15 for full details.

---

**Errors Prevented**: 15 documented issues (Safari 18 Hide IP, Brave confetti, Next.js Jest, CSP blocking, token reuse, expiration, hostname allowlist, widget crash 300030, config error 600010, missing validation, GET request, secret exposure, Chrome/Edge 106010, multiple widgets rendering, token regeneration pattern)