Nuxt4 Turnstile

Cloudflare Turnstile integration for Nuxt 4 - A privacy-focused CAPTCHA alternative.

✨ Features

• 🔒 Privacy-focused - No tracking, no cookies, no fingerprinting
• 🚀 Nuxt 4 Compatible - Built specifically for Nuxt 4
• 📦 Auto-imported - Components and composables ready to use
• 🛡️ Server Validation - Built-in server-side token verification
• 🎨 Customizable - Theme, size, appearance options
• ♻️ Auto-refresh - Automatically refreshes tokens before expiry
• 📝 TypeScript - Full TypeScript support

📦 Installation

# npm
npm install nuxt4-turnstile

# pnpm
pnpm add nuxt4-turnstile

# bun
bun add nuxt4-turnstile

⚙️ Configuration

Add nuxt4-turnstile to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt4-turnstile'],

  turnstile: {
    siteKey: 'your-site-key', // Get from Cloudflare Dashboard
  },

  runtimeConfig: {
    turnstile: {
      // Override with NUXT_TURNSTILE_SECRET_KEY env variable
      secretKey: '',
    },
  },
})

Get Your Keys

1. Go to Cloudflare Turnstile
2. Create a new site
3. Copy your Site Key (public) and Secret Key (server-side)

Configuration Options

🚀 Usage

Component

Use the auto-imported <NuxtTurnstile> component:

<template>
  <form @submit.prevent="onSubmit">
    <NuxtTurnstile v-model="token" />
    <button type="submit" :disabled="!token">Submit</button>
  </form>
</template>

<script setup>
const token = ref('')

async function onSubmit() {
  // Send token to your server for verification
  await $fetch('/api/contact', {
    method: 'POST',
    body: { token, message: '...' }
  })
}
</script>

[!TIP] If you are using a form component that restricts content (like Nuxt UI Pro's <AuthForm>), make sure to place <NuxtTurnstile> in a supported slot (e.g., #validation or #footer) instead of the default slot.

Component Props

Component Events

Component Methods (via ref)

<template>
  <NuxtTurnstile ref="turnstile" v-model="token" />
  <button @click="turnstile?.reset()">Reset</button>
</template>

<script setup>
const turnstile = ref()
const token = ref('')
</script>

🛡️ Server Verification

Using the Built-in Endpoint

Enable the validation endpoint in your config:

export default defineNuxtConfig({
  turnstile: {
    siteKey: '...',
    addValidateEndpoint: true,
  },
})

Then call it from your client:

const { success } = await $fetch('/_turnstile/validate', {
  method: 'POST',
  body: { token }
})

Using the Helper Function

In your server routes:

// server/api/contact.post.ts
export default defineEventHandler(async (event) => {
  const { token, message } = await readBody(event)

  // Verify the token
  const result = await verifyTurnstileToken(token)

  if (!result.success) {
    throw createError({
      statusCode: 400,
      message: 'Invalid captcha'
    })
  }

  // Continue with your logic...
  return { success: true }
})

Verification Options

await verifyTurnstileToken(token, {
  secretKey: 'override-secret',  // Override config secret
  remoteip: '1.2.3.4',           // Client IP for security
  action: 'login',               // Validate expected action
  cdata: 'user-123',             // Validate expected cdata
})

🔧 Composable

Use the useTurnstile composable for programmatic access:

const {
  isAvailable,  // Is Turnstile loaded?
  siteKey,      // Get site key
  verify,       // Verify token via endpoint
  render,       // Render widget programmatically
  reset,        // Reset widget
  remove,       // Remove widget
  getResponse,  // Get token
  isExpired,    // Check expiry
  execute,      // Execute invisible challenge
} = useTurnstile()

🌐 Environment Variables

Override configuration with environment variables:

NUXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
NUXT_TURNSTILE_SECRET_KEY=your-secret-key

📝 TypeScript

Types are automatically available:

import type {
  TurnstileInstance,
  TurnstileOptions,
  TurnstileVerifyResponse,
} from 'nuxt4-turnstile'

🧪 Testing

For testing, use Cloudflare's test keys:

Secret test keys:

📄 License

MIT License - see LICENSE for details.