Nuxt Turnstile

Configure the module in your nuxt.config.ts. You must provide a siteKey and a secretKey (via runtimeConfig or an environment variable).

Configuration Options:

• siteKey: Your Cloudflare Turnstile site key.
• secretKey: Your Cloudflare Turnstile secret key. Can be set in runtimeConfig or via the NUXT_TURNSTILE_SECRET_KEY environment variable.
• secretKeyPath: A path to a file containing the secret key. This is read at build-time and overrides other secretKey settings.
• addValidateEndpoint: Boolean. If true, enables a built-in validation endpoint at /_turnstile/validate.

Environment Variable Overrides:

• NUXT_PUBLIC_TURNSTILE_SITE_KEY overrides the site key.
• NUXT_TURNSTILE_SECRET_KEY overrides the secret key.

export default defineNuxtConfig({
  modules: ['@nuxtjs/turnstile'],

  turnstile: {
    siteKey: '<your-site-key>',
  },

  runtimeConfig: {
    turnstile: {
      // This can be overridden at runtime via the NUXT_TURNSTILE_SECRET_KEY
      // environment variable.
      secretKey: '',
    },
  },
})

The <NuxtTurnstile> component is an auto-imported Vue component used to render the Turnstile widget.

• Token Access: Use v-model to bind the validation token to a variable.
• Form Integration: Cloudflare automatically adds a hidden form element named cf-turnstile-response to your form. Alternatively, you can send the token explicitly via the v-model value.
• Customization: You can pass an options object to configure the widget and use the element prop to change the default <div> wrapper to a different element.
• Token Lifecycle: Tokens are valid for 300s and are automatically revalidated after 250s.
• Manual Reset: Because tokens are invalidated after server-side processing, you must regenerate the token for subsequent submissions (e.g., in a multi-submission form) using the reset() method via a template ref.

<template>
  <div>
    <form @submit.prevent="onSubmit">
      <NuxtTurnstile v-model="token" />
      <input type="submit" />
    </form>
  </div>
</template>

The @nuxtjs/turnstile module can be configured via the turnstile key in your nuxt.config.ts.

Configuration Options

export interface ModuleOptions {
  secretKey?: string
  secretKeyPath?: string
  siteKey?: string
  addValidateEndpoint?: boolean
}

Use the verifyTurnstileToken utility to validate a Cloudflare Turnstile token on your server. This function performs a POST request to the Cloudflare siteverify endpoint using the secretKey configured in your Nuxt runtime configuration.

Parameters:

• token (string): The Turnstile token received from the client.
• event (H3Event, optional): The H3 event object, required to access the runtime configuration via useRuntimeConfig in Nitro environments.
• signal (AbortSignal, optional): An optional signal to abort the fetch request.

Returns:

• A Promise that resolves to a TurnstileValidationResponse object containing the verification result from Cloudflare.

import { verifyTurnstileToken }

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const token = body.token

  const isValid = await verifyTurnstileToken(token, event)

  if (!isValid.success) {
    throw createError({
      statusCode: 403,
      statusMessage: 'Invalid Turnstile token'
    })
  }

  return { success: true }
})

When rendering a Turnstile widget, you can pass a TurnstileRenderOptions object to customize its behavior, appearance, and callbacks.

Key options include:

• sitekey: The sitekey associated with your widget configuration.
• theme: Sets the widget theme to 'dark', 'light', or 'auto' (default).
• appearance: Controls visibility. Options are 'always' (default), 'execute', or 'interaction-only'.
• language: A custom language setting (e.g., 'en', 'en-US', or 'auto').
• action: A string used to differentiate widgets in analytics.
• cData: A custom payload attached to the challenge and returned upon validation.
• callback: A function invoked upon successful challenge completion, receiving the token as a string.
• expired-callback: A function invoked when a challenge expires.
• error-callback: A function invoked when a network error occurs.
• tabindex: The tabindex for the iframe (default is 0).

const options: TurnstileRenderOptions = {
  sitekey: 'YOUR_SITE_KEY',
  theme: 'dark',
  appearance: 'always',
  callback: (token: string) => {
    console.log('Success! Token:', token);
  },
  'error-callback': () => {
    console.error('Network error occurred');
  }
};