Nuxt hCaptcha

🚧 Note: This project is currently under development and not yet production ready.

Nuxt module that allows to protect your website from bots. Heavily inspired by Nuxt Turnstile.

Quick Setup

1. Add nuxt-hcaptcha-module dependency to your project

# Using pnpm
pnpm add -D nuxt-hcaptcha-module

# Using yarn
yarn add --dev nuxt-hcaptcha-module

# Using npm
npm install --save-dev nuxt-hcaptcha-module

2. Add nuxt-hcaptcha-module to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-hcaptcha-module'
  ]
})

3. Set siteKey and secretKey generated in hCaptcha dashboard

export default defineNuxtConfig({
  modules: ["nuxt-hcaptcha-module"],
  hcaptcha: {
    siteKey: 'YOUR_SITE_KEY',
    secretKey: 'YOUR_SECRET_KEY'
  }
});

You can also use environment variables:

HCAPTCHA_SITE_KEY=YOUR_SITE_KEY
HCAPTCHA_SECRET_KEY=YOUR_SECRET_KEY

4. Use NuxtHCaptcha component in your application

<template>
  <form @submit.prevent="sendForm">
    <!-- put your form fields here -->
    <NuxtHCaptcha v-model="form.token" />
    <button>submit</button>
  </form>
</template>

<script setup>
const form = ref({
  token: ''
})

async function sendForm () {
  await $fetch('/api/your-api-endpoint', {
    method: 'POST',
    body: form.value
  })
}
</script>

5. Use verifyHCaptchaToken to validate hCaptcha token (only when you use server routes)

// server/api/your-api-endpoint.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const captchaResponse = await verifyHCaptchaToken(body.token)

  // return an error when hCaptcha detects a bot
  if (!captchaResponse.success) {
    return createError({
      statusCode: 401
    })
  }

  // handle logic for verified user, for example:
  // await createUser({ user: body.user })

  return ({ success: true })
})

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release