A Vue3 component for integrating Cloudflare Turnstile into your application.
If you appreciate my work, please consider giving it a star! 🤩 or a
- 🔒 Easy integration with Cloudflare Turnstile CAPTCHA
- 🌐 Server-side verification helpers for Express, Cloudflare Pages, and Workers
- 🎨 Customizable appearance (theme, size, language)
- ⚡ Full TypeScript support
- 🔄 Auto-reset functionality
- 🧩 Vue 3 Composition API compatible
- Turnstile Vue3 Component
To install the Turnstile Vue3 component, run the following command:
npm install @sctg/turnstile-vue3Here is an example of how to use the Turnstile Vue3 component in your Vue3 application using the Composition API:
<script setup lang="ts">
import { Turnstile } from '@sctg/turnstile-vue3';
import { ref } from 'vue';
const token = ref<string | null>(null);
const siteKey = 'YOUR_SITE_KEY';
const handleSuccess = () => {
console.log('Turnstile token:', token.value);
fetch('/api/verify-captcha', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ token: token.value }),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error(error));
};
</script>
<template>
<div>
<Turnstile :site-key="siteKey" @complete="handleSuccess" v-model="token" />
</div>
</template>You can verify the captcha token on your server using the verifyCaptcha function:
import express from 'express';
import { verifyCaptcha } from '@sctg/turnstile-vue3';
const app = express();
app.use(express.json());
app.post('/api/verify-captcha', (req, res) => {
const { token } = req.body;
const turnstileSecret = 'YOUR_TURNSTILE_SECRET';
verifyCaptcha(turnstileSecret, token, req.ip)
.then((data) => {
if (data.success) {
res.json({ message: 'Captcha verified successfully' });
} else {
res.status(401).json({ message: 'Invalid captcha' });
}
})
.catch((error) => {
res.status(500).json({ message: 'Error verifying captcha' });
});
});
app.listen(3000, () => {
console.log('Server started on port 3000');
});For Cloudflare Pages, you can create a function to handle verification:
// filepath: functions/api/verify-captcha.ts
import { verifyCaptcha } from '@sctg/turnstile-vue3';
export async function onRequestPost({ request, env }) {
const body = await request.json();
const token = body.token;
const turnstileSecret = env.CLOUDFLARE_TURNSTILE_SECRET_KEY;
const data = await verifyCaptcha(turnstileSecret, token, request.headers.get('CF-Connecting-IP'))
if (data.success) {
return new Response(
JSON.stringify({ message: 'Captcha verified successfully' }),
{
status: 200,
headers: {
'Content-Type': 'application/json',
},
},
);
} else {
return new Response(JSON.stringify({ message: 'Invalid captcha' }), {
status: 400,
headers: {
'Content-Type': 'application/json',
},
});
}
}Here is an example of how to use the verifyCaptcha function in a Cloudflare worker:
import { verifyCaptcha } from '@sctg/turnstile-vue3';
addEventListener('fetch', (event) => {
event.respondWith(handleRequest(event.request));
});
async function handleRequest(request) {
const { url, method } = request;
if (method === 'POST' && url.pathname === '/verify-captcha') {
const { token } = await request.json();
const turnstileSecret = 'YOUR_TURNSTILE_SECRET';
try {
const data = await verifyCaptcha(turnstileSecret, token, request.headers.get('CF-Connecting-IP'));
if (data.success) {
return new Response('Captcha verified successfully', { status: 200 });
} else {
return new Response('Invalid captcha', { status: 401 });
}
} catch (error) {
return new Response('Error verifying captcha', { status: 500 });
}
}
return new Response('Method not allowed', { status: 405 });
}The project includes a working demo that shows how to use the component with Cloudflare Pages Functions. The demo features:
- A simple form protected by Turnstile
- Server-side verification using Cloudflare Pages Functions
- Environment variable configuration
To run the demo:
- Clone the repository
- Install dependencies:
cd demo
npm install- Create a .env file with your Cloudflare Turnstile keys:
CLOUDFLARE_TURNSTILE_SITE_KEY=your_site_key
CLOUDFLARE_TURNSTILE_SECRET_KEY=your_secret_key- Start the development server:
npm run dev:env - Open your browser and navigate to
http://localhost:8788
- Vue 3.x
- TypeScript (recommended but not required)
- A Cloudflare Turnstile account and API keys
The Turnstile component has the following props:
-
siteKey: The site key for your Turnstile account. -
modelValue: The initial value for the Turnstile token. -
resetInterval: The interval (in milliseconds) before the Turnstile is reset. Default is 295000 (5 minutes). -
size: The size of the Turnstile widget. Can be one of the following:normal: The default size.flexible: A flexible size that adapts to the container.compact: A compact size that is smaller than the default size.
-
theme: The theme of the Turnstile widget. Can be one of the following:light: A light theme.dark: A dark theme.auto: Automatically detects the theme based on the surrounding environment.
-
language: The language of the Turnstile widget. Can be one of the following:auto: Automatically detects the language based on the surrounding environment.- A valid language code (e.g.,
en,fr,es, etc.).
-
action: The action that the Turnstile widget is verifying. Can be any string. -
appearance: The appearance of the Turnstile widget. Can be one of the following:always: Always shows the Turnstile widget.execute: Shows the Turnstile widget only when the user interacts with the element.interaction-only: Shows the Turnstile widget only when the user interacts with the element, and hides it when the interaction is completed.
-
renderOnMount: Whether to render the Turnstile widget when the component is mounted. Default istrue. -
v-model: A two-way binding for the Turnstile token.
The Turnstile component emits the following events:
update:modelValue: Updates themodelValueprop with the new Turnstile token.complete: Emitted when the Turnstile challenge is completed successfully.error: Emitted when an error occurs.unsupported: Emitted when the Turnstile widget is not supported.expired: Emitted when the Turnstile widget has expired.before-interactive: Emitted when the Turnstile widget is about to become interactive.after-interactive: Emitted when the Turnstile widget becomes interactive.
This project is licensed under the AGPLv3 license. This means:
- You can use this package in your project
- You must disclose the source code of your application if it uses this library and is accessible over a network
- Any modifications to this library must be released under the same license
- For more details, see the LICENSE file
If you require a different licensing arrangement for commercial use, please contact the author.
Contributions to this library are welcome! Please open an issue or submit a pull request for any changes you'd like to make.
Ensure your site key is correct and that you've properly configured domains in your Cloudflare dashboard.
Check that your secret key is correct and that you're passing the client IP address correctly.
Adjust the resetInterval prop to match your requirements (default is 5 minutes).
This library is not affiliated with Cloudflare. It's just a convenient wrapper around the Turnstile API.