Cloudflare Turnstile

Status: Production Ready ✅ Last Updated: 2026-01-21 Dependencies: None (optional: @marsidev/react-turnstile for React) Latest Versions: @marsidev/react-turnstile@1.4.1, turnstile-types@1.2.3

Recent Updates (2025):

December 2025: @marsidev/react-turnstile v1.4.1 fixes race condition in script loading August 2025: v1.3.0 adds rerenderOnCallbackChange prop for React closure issues March 2025: Upgraded Turnstile Analytics with TopN statistics (7 dimensions: hostnames, browsers, countries, user agents, ASNs, OS, source IPs), anomaly detection, enhanced bot behavior monitoring January 2025: Brief remoteip validation enforcement (resolved, but highlights importance of correct IP passing) 2025: WCAG 2.1 AA compliance, Free plan (20 widgets, 7-day analytics), Enterprise features (unlimited widgets, ephemeral IDs, any hostname support, 30-day analytics, offlabel branding) Quick Start (5 Minutes)

Copy sitekey (public) and secret key (private)

3. Validate token server-side (Cloudflare Workers)

const formData = await request.formData() const token = formData.get('cf-turnstile-response')

const verifyFormData = new FormData() verifyFormData.append('secret', env.TURNSTILE_SECRET_KEY) verifyFormData.append('response', token) verifyFormData.append('remoteip', request.headers.get('CF-Connecting-IP')) // REQUIRED - see Critical Rules

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', { status: 401 })

CRITICAL:

Token expires in 5 minutes, single-use only ALWAYS validate server-side (Siteverify API required) Never proxy/cache api.js (must load from Cloudflare CDN) Use different widgets for dev/staging/production Rendering Modes

Implicit (auto-render on page load):

Explicit (programmatic control for SPAs):

const widgetId = turnstile.render('#container', { sitekey: 'YOUR_SITE_KEY' }) turnstile.reset(widgetId) // Reset widget turnstile.getResponse(widgetId) // Get token

React (using @marsidev/react-turnstile):

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

Critical Rules Always Do

✅ Call Siteverify API - Server-side validation is mandatory ✅ Use HTTPS - Never validate over HTTP ✅ Protect secret keys - Never expose in frontend code ✅ Handle token expiration - Tokens expire after 5 minutes ✅ Implement error callbacks - Handle failures gracefully ✅ Use dummy keys for testing - Test sitekey: 1x00000000000000000000AA ✅ Set reasonable timeouts - Don't wait indefinitely for validation ✅ Validate action/hostname - Check additional fields when specified ✅ Rotate keys periodically - Use dashboard or API to rotate secrets ✅ Monitor analytics - Track solve rates and failures ✅ Always pass client IP to Siteverify - Use CF-Connecting-IP header (Workers) or X-Forwarded-For (Node.js). Cloudflare briefly enforced strict remoteip validation in Jan 2025, causing widespread failures for sites not passing correct IP

Never Do

❌ Skip server validation - Client-side only = security vulnerability ❌ Proxy api.js script - Must load from Cloudflare CDN ❌ Reuse tokens - Each token is single-use only ❌ Use GET requests - Siteverify only accepts POST ❌ Expose secret key - Keep secrets in backend environment only ❌ Trust client-side validation - Tokens can be forged ❌ Cache api.js - Future updates will break your integration ❌ Use production keys in tests - Use dummy keys instead ❌ Ignore error callbacks - Always handle failures

Known Issues Prevention

This skill prevents 15 documented issues:

Issue #1: Missing Server-Side Validation

Error: Zero token validation in Turnstile Analytics dashboard Source: https://developers.cloudflare.com/turnstile/get-started/ Why It Happens: Developers only implement client-side widget, skip Siteverify call Prevention: All templates include mandatory server-side validation with Siteverify API

Issue #2: Token Expiration (5 Minutes)

Error: success: false for valid tokens submitted after delay Source: https://developers.cloudflare.com/turnstile/get-started/server-side-validation Why It Happens: Tokens expire 300 seconds after generation Prevention: Templates document TTL and implement token refresh on expiration

Issue #3: Secret Key Exposed in Frontend

Error: Security bypass - attackers can validate their own tokens Source: https://developers.cloudflare.com/turnstile/get-started/server-side-validation Why It Happens: Secret key hardcoded in JavaScript or visible in source Prevention: All templates show backend-only validation with environment variables

Issue #4: GET Request to Siteverify

Error: API returns 405 Method Not Allowed Source: https://developers.cloudflare.com/turnstile/migration/recaptcha Why It Happens: reCAPTCHA supports GET, Turnstile requires POST Prevention: Templates use POST with FormData or JSON body

Issue #5: Content Security Policy Blocking

Error: Error 200500 - "Loading error: The iframe could not be loaded" Source: https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes Why It Happens: CSP blocks challenges.cloudflare.com iframe Prevention: Skill includes CSP configuration reference and check-csp.sh script

Issue #6: Widget Crash (Error 300030)

Error: Generic client execution error for legitimate users Source: https://community.cloudflare.com/t/turnstile-is-frequently-generating-300x-errors/700903 Why It Happens: Unknown - appears to be Cloudflare-side issue (2025) Prevention: Templates implement error callbacks, retry logic, and fallback handling

Issue #7: Configuration Error (Error 600010)

Error: Widget fails with "configuration error" Source: https://community.cloudflare.com/t/repeated-cloudflare-turnstile-error-600010/644578 Why It Happens: Missing or deleted hostname in widget configuration Prevention: Templates document hostname allowlist requirement and verification steps

Issue #8: Safari 18 / macOS 15 "Hide IP" Issue

Error: Error 300010 when Safari's "Hide IP address" is enabled Source: https://community.cloudflare.com/t/turnstile-is-frequently-generating-300x-errors/700903 Why It Happens: Privacy settings interfere with challenge signals Prevention: Error handling reference documents Safari workaround (disable Hide IP)

Issue #9: Brave Browser Confetti Animation Failure

Error: Verification fails during success animation Source: https://github.com/brave/brave-browser/issues/45608 (April 2025) Why It Happens: Brave shields block animation scripts Prevention: Templates handle success before animation completes

Issue #10: Next.js + Jest Incompatibility

Error: @marsidev/react-turnstile breaks Jest tests Source: https://github.com/marsidev/react-turnstile/issues/112 (Oct 2025) Why It Happens: Module resolution issues with Jest Prevention: Testing guide includes Jest mocking patterns and dummy sitekey usage

Issue #11: localhost Not in Allowlist

Error: Error 110200 - "Unknown domain: Domain not allowed" Source: https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes Why It Happens: Production widget used in development without localhost in allowlist Prevention: Templates use dummy test keys for dev, document localhost allowlist requirement

Issue #12: Token Reuse Attempt

Error: success: false with "token already spent" error Source: https://developers.cloudflare.com/turnstile/troubleshooting/testing Why It Happens: Each token can only be validated once. Turnstile tokens are single-use - after validation (success OR failure), the token is consumed and cannot be revalidated. Developers must explicitly call turnstile.reset() to generate a new token for subsequent submissions. Prevention: Templates document single-use constraint and token refresh patterns

// CRITICAL: Reset widget after validation to get new token const turnstileRef = useRef(null)

async function handleSubmit(e) { e.preventDefault() const token = formData.get('cf-turnstile-response')

const result = await fetch('/api/submit', { method: 'POST', body: JSON.stringify({ token }) })

// Reset widget regardless of success/failure // Token is consumed either way if (turnstileRef.current) { turnstile.reset(turnstileRef.current) } }

Issue #13: Error 106010 - Chrome/Edge First-Load Failure

Error: 106010 - "Generic parameter error" on first widget load in Chrome/Edge browsers Source: Cloudflare Error Codes, Community Report Why It Happens: Unknown browser-specific issue affecting Chrome and Edge on first page load. Console shows 400 error to https://challenges.cloudflare.com/cdn-cgi/challenge-platform. Firefox is not affected. Subsequent page reloads work correctly. Prevention: Implement error callback with auto-retry logic

turnstile.render('#container', { sitekey: SITE_KEY, retry: 'auto', 'retry-interval': 8000, 'error-callback': (errorCode) => { if (errorCode === '106010') { console.warn('Chrome/Edge first-load issue (106010), auto-retrying...') // Auto-retry will handle it } } })

Workaround: Widget works correctly after page reload. Auto-retry setting resolves in most cases. Test in Incognito mode to rule out browser extensions. Review CSP rules to ensure Cloudflare Turnstile endpoints are allowed.

Issue #14: Multiple Widgets Visual Status Stuck (Community-sourced)

Error: Widget displays "Pending..." status even after successful token generation Source: GitHub Issue #119 Why It Happens: CSS repaint issue when rendering multiple components on a single page. Only reproducible on full HD desktop screens. Token IS successfully generated (validation works), but visual status doesn't update. Hovering over widget triggers repaint and shows correct status. Prevention: Force CSS repaint in success callback

{ setToken(token) // Force repaint by toggling display const widget = document.querySelector('.cf-turnstile') if (widget) { widget.style.display = 'none' setTimeout(() => widget.style.display = 'block', 0) } }} />

Note: This is a visual-only issue, not a validation failure. The token is correctly generated and functional.

Issue #15: Jest Compatibility with @marsidev/react-turnstile (Updated Dec 2025)

Error: Jest encountered an unexpected token when importing @marsidev/react-turnstile Source: GitHub Issue #114, GitHub Issue #112 Why It Happens: ESM module resolution issues with Jest 30.2.0 (latest as of Dec 2025). Issue #112 closed as "not planned" by maintainer. Jest users are stuck; Vitest migration works. Prevention: Mock the Turnstile component in Jest setup OR migrate to Vitest

// Option 1: Jest mocking (jest.setup.ts) jest.mock('@marsidev/react-turnstile', () => ({ Turnstile: () =>

, }))

// 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:

{ "vars": { "TURNSTILE_SITE_KEY": "1x00000000000000000000AA" }, "secrets": ["TURNSTILE_SECRET_KEY"] // Run: wrangler secret put TURNSTILE_SECRET_KEY }

Required CSP:

Common Patterns Pattern 1: Hono + Cloudflare Workers 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 '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 (

</p>
<pre class="codehilite"><code>  <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>
</code></pre>

<p>)
}</p>
<p>When to use: Client-side forms in Next.js with React hooks</p>
<p>Testing Keys</p>
<p>Dummy Sitekeys (client):</p>
<p>Always pass: 1x00000000000000000000AA
Always block: 2x00000000000000000000AB
Force interactive: 3x00000000000000000000FF</p>
<p>Dummy Secret Keys (server):</p>
<p>Always pass: 1x0000000000000000000000000000000AA
Always fail: 2x0000000000000000000000000000000AA
Token already spent: 3x0000000000000000000000000000000AA
Bundled Resources</p>
<p>Scripts: check-csp.sh - Verify CSP allows Turnstile</p>
<p>References:</p>
<p>widget-configs.md - All configuration options
error-codes.md - Error code troubleshooting (100<em>/200</em>/300<em>/400</em>/600*)
testing-guide.md - Testing strategies, dummy keys
react-integration.md - React/Next.js patterns</p>
<p>Templates: Complete examples for Hono, React, implicit/explicit rendering, validation</p>
<p>Advanced Features</p>
<p>Pre-Clearance (SPAs): Issue cookie that persists across page navigations</p>
<p>turnstile.render('#container', {
  sitekey: SITE_KEY,
  callback: async (token) => {
    await fetch('/api/pre-clearance', { method: 'POST', body: JSON.stringify({ token }) })
  }
})</p>
<p>Custom Actions & Data: Track challenge types, pass custom data (max 255 chars)</p>
<p>turnstile.render('#container', {
  action: 'login',  // Track in analytics
  cdata: JSON.stringify({ userId: '123' }),  // Custom payload
})</p>
<p>Error Handling: Use retry: 'auto' and error-callback for resilience</p>
<p>turnstile.render('#container', {
  retry: 'auto',
  'retry-interval': 8000,  // ms between retries
  'error-callback': (error) => { /<em> handle or show fallback </em>/ }
})</p>
<p>Dependencies</p>
<p>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</p>
<p>Official Documentation
https://developers.cloudflare.com/turnstile/
Use mcp__cloudflare-docs__search_cloudflare_documentation tool
Troubleshooting
Problem: Error 110200 - "Unknown domain"</p>
<p>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.</p>
<p>Problem: Error 300030 - Widget crashes for legitimate users</p>
<p>Solution: Implement error callback with retry logic. This is a known Cloudflare-side issue (2025). Fallback to alternative verification if retries fail.</p>
<p>Problem: Tokens always return success: false</p>
<p>Solution:</p>
<p>Check token hasn't expired (5 min TTL)
Verify secret key is correct
Ensure token hasn't been validated before (single-use)
Check hostname matches widget configuration
Problem: CSP blocking iframe (Error 200500)</p>
<p>Solution: Add CSP directives:</p>
<p><meta http-equiv="Content-Security-Policy" content="
  frame-src https://challenges.cloudflare.com;
  script-src https://challenges.cloudflare.com;
"></p>
<p>Problem: Safari 18 "Hide IP" causing Error 300010</p>
<p>Solution: Document in error message that users should disable Safari's "Hide IP address" setting (Safari → Settings → Privacy → Hide IP address → Off)</p>
<p>Problem: Next.js + Jest tests failing with @marsidev/react-turnstile</p>
<p>Solution: Mock the Turnstile component in Jest setup (or migrate to Vitest, which handles ESM modules correctly):</p>
<p>// Option 1: Jest mocking (jest.setup.ts)
jest.mock('@marsidev/react-turnstile', () => ({
  Turnstile: () => <div data-testid="turnstile-mock" />,
}))</p>
<p>// Option 2: Migrate to Vitest (recommended for new projects)
// Vitest handles ESM modules without mocking required</p>
<p>Note: This issue persists in Jest 30.2.0 (Dec 2025). Maintainer closed as "not planned". See Issue #15 for full details.</p>
<p>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)</p>
                </article>

<a href="/" class="back-link">← <span data-i18n="detail.backToLeaderboard">返回排行榜</span></a>
            </div>

<aside class="sidebar">
                <section class="related-skills" id="relatedSkillsSection">
                    <h2 class="related-title" data-i18n="detail.relatedSkills">相关 Skills</h2>
                    <div class="related-list" id="relatedSkillsList">
                        
                        <div class="skeleton-card"></div>
                        <div class="skeleton-card"></div>
                        <div class="skeleton-card"></div>
                    </div>
                </section>
            </aside>
        </div>
    </div>

// Load language files (only current + fallback for performance)
        async function loadLanguageResources() {
            const savedLang = localStorage.getItem('i18nextLng') || 'en';
            const langsToLoad = new Set([savedLang, 'en']); // current + fallback
            await Promise.all([...langsToLoad].map(async (lang) => {
                try {
                    const response = await fetch(`/locales/${lang}.json`);
                    if (response.ok) {
                        resources[lang] = { translation: await response.json() };
                    }
                } catch (error) {
                    console.warn(`Failed to load ${lang} language file:`, error);
                }
            }));
        }

// Load a single language on demand (for language switching)
        async function loadLanguage(lang) {
            if (resources[lang]) return;
            try {
                const response = await fetch(`/locales/${lang}.json`);
                if (response.ok) {
                    resources[lang] = { translation: await response.json() };
                    i18next.addResourceBundle(lang, 'translation', resources[lang].translation);
                }
            } catch (error) {
                console.warn(`Failed to load ${lang} language file:`, error);
            }
        }

// Initialize i18next
        async function initI18n() {
            try {
                await loadLanguageResources();
                
                // Filter out null values from resources
                const validResources = {};
                for (const [lang, data] of Object.entries(resources)) {
                    if (data !== null) {
                        validResources[lang] = data;
                    }
                }
                
                console.log('Loaded languages:', Object.keys(validResources));
                console.log('zh-CN resource:', validResources['zh-CN']);
                console.log('detail.home in resource:', validResources['zh-CN']?.translation?.detail?.home);
                
                // 检查是否有保存的语言偏好
                const savedLang = localStorage.getItem('i18nextLng');
                // 如果没有保存的语言偏好，默认使用英文
                const defaultLang = savedLang && ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'].includes(savedLang) 
                    ? savedLang 
                    : 'en';
                
                await i18next
                    .use(i18nextBrowserLanguageDetector)
                    .init({
                        lng: defaultLang,  // 强制设置初始语言
                        fallbackLng: 'en',
                        supportedLngs: ['zh-CN', 'en', 'ja', 'ko', 'zh-TW', 'es', 'fr'],
                        resources: validResources,
                        detection: {
                            order: ['localStorage'],  // 只使用 localStorage，不检测浏览器语言
                            caches: ['localStorage'],
                            lookupLocalStorage: 'i18nextLng'
                        },
                        interpolation: {
                            escapeValue: false
                        }
                    });

console.log('i18next initialized, language:', i18next.language);
                console.log('Test translation:', i18next.t('detail.home'));

// Set initial language in selector
                const langSwitcher = document.getElementById('langSwitcher');
                langSwitcher.value = i18next.language;

// Update page language
                updatePageLanguage();

// Language switch event
                langSwitcher.addEventListener('change', async (e) => {
                    await loadLanguage(e.target.value); // load on demand
                    i18next.changeLanguage(e.target.value).then(() => {
                        updatePageLanguage();
                        localStorage.setItem('i18nextLng', e.target.value);
                    });
                });
            } catch (error) {
                console.error('i18next init failed:', error);
            }
        }

// Translation helper
        function t(key, options = {}) {
            return i18next.t(key, options);
        }

// Update all translatable elements
        function updatePageLanguage() {
            // Update HTML lang attribute
            document.documentElement.lang = i18next.language;

// Update elements with data-i18n attribute
            document.querySelectorAll('[data-i18n]').forEach(el => {
                const key = el.getAttribute('data-i18n');
                el.textContent = t(key);
            });
        }

// Copy command function
        function copyCommand() {
            const command = document.getElementById('installCommand').textContent;
            const btn = document.getElementById('copyBtn');
            
            navigator.clipboard.writeText(command).then(() => {
                btn.textContent = t('copied');
                btn.classList.add('copied');
                setTimeout(() => {
                    btn.textContent = t('copy');
                    btn.classList.remove('copied');
                }, 2000);
            }).catch(() => {
                // Fallback for non-HTTPS
                const textArea = document.createElement('textarea');
                textArea.value = command;
                textArea.style.position = 'fixed';
                textArea.style.left = '-9999px';
                document.body.appendChild(textArea);
                textArea.select();
                document.execCommand('copy');
                document.body.removeChild(textArea);
                
                btn.textContent = t('copied');
                btn.classList.add('copied');
                setTimeout(() => {
                    btn.textContent = t('copy');
                    btn.classList.remove('copied');
                }, 2000);
            });
        }

// Initialize
        document.getElementById('copyBtn').addEventListener('click', copyCommand);
        initI18n();

// 异步加载相关 Skills
        async function loadRelatedSkills() {
            const owner = 'jezweb';
            const skillName = 'cloudflare-turnstile';
            const currentLang = 'zh-TW';
            const listContainer = document.getElementById('relatedSkillsList');
            const section = document.getElementById('relatedSkillsSection');

try {
                const response = await fetch(`/api/related-skills/${encodeURIComponent(owner)}/${encodeURIComponent(skillName)}?limit=6`);
                
                if (!response.ok) {
                    throw new Error('Failed to load');
                }

const data = await response.json();
                const relatedSkills = data.related_skills || [];

if (relatedSkills.length === 0) {
                    // 没有相关推荐时隐藏整个区域
                    section.style.display = 'none';
                    return;
                }

// 渲染相关 Skills
                listContainer.innerHTML = relatedSkills.map(skill => {
                    const desc = skill.description || '';
                    const truncatedDesc = desc.length > 60 ? desc.substring(0, 60) + '...' : desc;
                    return `
                        <a href="${currentLang === 'en' ? '' : '/' + currentLang}/skill/${skill.owner}/${skill.repo}/${skill.skill_name}" class="related-card">
                            <div class="related-name">${escapeHtml(skill.skill_name)}</div>
                            <div class="related-meta">
                                <span class="related-owner">${escapeHtml(skill.owner)}</span>
                                <span class="related-installs">${skill.installs}</span>
                            </div>
                            <div class="related-desc">${escapeHtml(truncatedDesc)}</div>
                        </a>
                    `;
                }).join('');

} catch (error) {
                console.error('Failed to load related skills:', error);
                // 加载失败时显示提示或隐藏
                listContainer.innerHTML = '<div class="related-empty">暂无相关推荐</div>';
            }
        }

// HTML 转义
        function escapeHtml(text) {
            const div = document.createElement('div');
            div.textContent = text;
            return div.innerHTML;
        }

// 页面加载完成后异步加载相关 Skills
        if (document.readyState === 'loading') {
            document.addEventListener('DOMContentLoaded', loadRelatedSkills);
        } else {
            loadRelatedSkills();
        }
    </script>

</body>
</html>

cloudflare-turnstile

安装

1. Create widget: https://dash.cloudflare.com/?to=/:account/turnstile

Copy sitekey (public) and secret key (private)

2. Add widget to frontend

3. Validate token server-side (Cloudflare Workers)