Nuxt Turnstile
Cloudflare Turnstile integration for Nuxt 3
Features
- 💪 smart verification with minimal user interaction
- 🕵️♀️ privacy-focused approach
- ✨ server validation helper for your nitro endpoints
- ⚡️ lightweight - script only loaded when required
Installation
-
First, follow these steps to obtain a free sitekey and secret key from Cloudflare.
-
Install and add @nuxtjs/turnstile
to your nuxt.config
.
pnpm add -D @nuxtjs/turnstile
npm install -D @nuxtjs/turnstile
yarn add -D @nuxtjs/turnstile
export default defineNuxtConfig({
modules: ['@nuxtjs/turnstile'],
runtimeConfig: {
turnstile: {
secretKey: process.env.NUXT_TURNSTILE_SECRET_KEY || '',
},
},
turnstile: {
siteKey: '<your-site-key>',
},
})
Tip: At runtime you can override site and secret keys with the NUXT_TURNSTILE_SECRET_KEY
and NUXT_PUBLIC_TURNSTILE_SITE_KEY
environment variables.
Usage
To use Turnstile, add the auto-imported Vue component in whatever component needs it:
<template>
<div>
<form @submit.prevent="onSubmit">
<Turnstile v-model="token" />
<input type="submit" />
</form>
</div>
</template>
<Turnstile>
can take a number of options via the options
argument. See all options. It renders the Turnstile <iframe>
within a <div>
wrapper by default, but you can configure this by setting the element
prop.
When in the page, it will automatically load the Turnstile script and validate your user. Each validation lasts for 300s, and @nuxtjs/turnstile
will automatically revalidate this token after 250s.
You can access the validation token by setting a v-model
on the component. Then, send the token along with your form responses, either explicitly or automatically (Cloudflare adds a hidden form element with the name cf-turnstile-response
to your form). To validate the token on server-side, you can use the auto-imported verifyTurnstileToken
utility in your Nitro server routes.
The turnstile token is no longer valid after being processed with CloudFlare via verifyTurnstileToken
. If you are using @nuxtjs/turnstile with a component that might need to be validated multiple times, such as a submission form, you will need to regenerate the token for each submission. To manually regenerate the token, @nuxtjs/turnstile exposes the reset
function directly via a template ref.
Example:
<template>
<Turnstile ref="turnstile" />
<button @click="turnstile.reset()">Reset token in template</button>
<button @click="reset()">Reset token from handler</button>
</template>
<script setup>
const turnstile = ref()
function reset() {
turnstile.value?.reset()
}
</script>
💻 Development
- Clone this repository
- Enable Corepack using
corepack enable
(use npm i -g corepack
for Node.js < 16.10) - Install dependencies using
pnpm install
- Stub module with
pnpm dev:prepare
- Run
pnpm dev
to start playground in development mode
Credits
License
Made with ❤️
Published under the MIT License.