Nuxt Yandex SmartCaptcha

A Nuxt 3/4 module providing integration with Yandex SmartCaptcha. Supports both visual widgets and programmatic captcha execution.

🌟 Features

• ✅ Nuxt 3/4 support
• ✅ TypeScript ready
• ✅ Flexible configuration via config and props
• ✅ Auto-load script
• ✅ Support for all Yandex SmartCaptcha parameters
• ✅ SSR compatible

🚀 Installation

npm install nuxt-yandex-smartcaptcha

⚙️ Configuration

Add the module to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-yandex-smartcaptcha'],
  
  yandexSmartCaptcha: {
    // Required parameter
    sitekey: 'YOUR_SITE_KEY_FROM_YANDEX',
    
    // Optional parameters
    lang: 'en',
    webview: false,
    test: false,
    invisible: false,
    shieldPosition: 'bottom-right',
    hideShield: false,
    autoLoad: true,
    onLoadCallback: 'onYandexCaptchaLoad'
  }
})

🔑 Getting Keys

1. Go to Yandex Cloud Console
2. Create a new "SmartCaptcha" service
3. Add your website domains
4. Copy client key (for frontend) and server key (for backend)

📖 Usage

YandexSmartCaptcha Component

Basic Usage

<template>
  <YandexSmartCaptcha @success="onSuccess" />
</template>

<script setup lang="ts">
const onSuccess = (token: string) => {
  console.log('Captcha completed:', token)
  // Send token to server for verification
}
</script>

With Custom Settings

<template>
  <YandexSmartCaptcha 
    sitekey="custom_sitekey"
    lang="en"
    :invisible="true"
    :test="true"
    shieldPosition="top-center"
    :hideShield="true"
    :callback="handleCallback"
    @success="onSuccess"
    @error="onError"
    @loaded="onLoaded"
  />
</template>

<script setup lang="ts">
const handleCallback = (token: string) => {
  console.log('Callback token:', token)
}

const onSuccess = (token: string) => {
  console.log('Success token:', token)
}

const onError = (error: Error) => {
  console.error('Captcha error:', error)
}

const onLoaded = () => {
  console.log('Captcha loaded')
}
</script>

Invisible Captcha with Auto-execution

<template>
  <form @submit.prevent="submitForm">
    <input v-model="email" placeholder="Email">
    <YandexSmartCaptcha 
      :invisible="true"
      :callback="onInvisibleCaptcha"
      ref="captchaRef"
    />
    <button type="submit">Submit</button>
  </form>
</template>

<script setup lang="ts">
const email = ref('')
const captchaRef = ref()

const onInvisibleCaptcha = (token: string) => {
  // Automatically called when needed
  console.log('Invisible captcha token:', token)
  submitToServer(token)
}

const submitToServer = async (token: string) => {
  // Send data to server
}
</script>

Manual Captcha Control

<template>
  <YandexSmartCaptcha ref="captchaRef" />
  <button @click="resetCaptcha">Reset Captcha</button>
  <button @click="getToken">Get Token</button>
</template>

<script setup lang="ts">
const captchaRef = ref()

const resetCaptcha = () => {
  if (captchaRef.value) {
    captchaRef.value.reset()
  }
}

const getToken = () => {
  if (captchaRef.value) {
    const token = captchaRef.value.getResponse()
    console.log('Current token:', token)
  }
}
</script>

🛡️ Server-Side Verification

// server/api/verify-captcha.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const { captchaToken } = body
  
  if (!captchaToken) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Captcha token is required'
    })
  }
  
  const verification = await $fetch('https://smartcaptcha.yandexcloud.net/validate', {
    method: 'POST',
    body: {
      secret: process.env.YANDEX_CAPTCHA_SECRET_KEY, // Server key
      token: captchaToken
    }
  })
  
  if (verification.status !== 'ok') {
    throw createError({
      statusCode: 400,
      statusMessage: 'Invalid captcha'
    })
  }
  
  return { success: true }
})

📋 API Reference

Module Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | sitekey | string | - | Required Site key | | lang | string | 'ru' | Interface language | | webview | boolean | false | Webview mode | | test | boolean | false | Test mode | | invisible | boolean | false | Invisible mode | | hideShield | boolean | false | Hide the block with the data processing notification | | shieldPosition | 'top-left' \| 'center-left' \| 'bottom-left' \| 'top-right' \| 'center-right' \| 'bottom-right' | 'bottom-right' | Shield position | | autoLoad | boolean | true | Auto-load script | | onLoadCallback | string | 'onYandexCaptchaLoad' | Callback function name |

Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | containerId | string | 'yandex-smartcaptcha-container' | Container ID | | sitekey | string | - | Site key (overrides config) | | lang | 'ru' \| 'en' \| 'be' \| 'kk' \| 'tt' \| 'uk' \| 'uz' | - | Interface language | | webview | boolean | - | Webview mode | | test | boolean | - | Test mode | | invisible | boolean | - | Invisible captcha | | hideShield | boolean | - | Hide the block with the data processing notification | | shieldPosition | 'top-left' \| 'center-left' \| 'bottom-left' \| 'top-right' \| 'center-right' \| 'bottom-right' | - | Shield position | | callback | (token: string) => void | - | Callback function |

Component Events

| Event | Parameters | Description | |-------|------------|-------------| | success | token: string | Captcha completed successfully | | error | error: Error | Loading or execution error | | loaded | - | Captcha loaded |

🎯 Configuration Priority

1. Component props (highest priority)
2. nuxt.config.ts config

❗ Important Notes

• Module works only on client side
• Properly configured sitekey is required
• In test mode captcha always passes successfully
• Don't forget to add domains in Yandex Cloud settings

🐛 Troubleshooting

Captcha Not Loading

• Check sitekey in config
• Ensure domain is added in Yandex Cloud
• Check browser console for errors

"Sitekey is required" Error

• Specify sitekey in nuxt.config.ts or component props

Script Not Loading

• Check internet connection
• Ensure autoLoad: true in config

📄 License

MIT