Nuxt ターンスタイル

Cloudflare ターンスタイルの Nuxt 3 統合

機能

💪 最小限のユーザー操作でスマート検証
🕵️‍♀️ プライバシー重視のアプローチ
✨ Nitro エンドポイントに使用するサーバー検証ヘルパー
⚡️ 軽量 - スクリプトは必要な場合にのみ読み込まれます

インストール

最初に、これらの手順に従って Cloudflare から無料のサイトキーとシークレットキーを取得します。
依存関係として @nuxt/scripts をインストールします。詳しく知りたい場合は、ドキュメントを参照してください。

@nuxtjs/turnstile をインストールし、nuxt.config に追加します。

npx nuxi@latest module add turnstile

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: '',
    },
  },
})

あるいは、turnstile.secretKeyPath をシークレットキーを含むファイルへのパスに設定できます。これにより、設定した他の明示的な secretKey がビルド時に読み取られ、上書きされます。

ヒント: ランタイム時に、NUXT_TURNSTILE_SECRET_KEY 環境変数と NUXT_PUBLIC_TURNSTILE_SITE_KEY 環境変数を使用して、サイトキーとシークレットキーを上書きできます。

使用

ターンスタイルを使用するには、通常以下を行います。

アプリ内で <NuxtTurnstile> コンポーネントを使用します（たとえば、お問い合わせフォームを構築するため）
API リクエストまたはフォーム送信を処理するときにサーバー上でトークンを検証します（たとえば、メールを送信する前）

クライアント

ターンスタイルを使用するには、必要なコンポーネントに自動インポートされた Vue コンポーネントを追加します

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

<NuxtTurnstile> は options 引数を使用して多数のオプションを使用できます。すべてのオプションを表示。デフォルトでは、ターンスタイルの <iframe> が <div> ラッパー内でレンダリングされますが、element プロパティを設定すると構成できます。

ページ内にある場合、ターンスタイルのスクリプトが自動的に読み込まれ、ユーザーが検証されます。それぞれの検証は 300 秒間持続し、@nuxtjs/turnstile は 250 秒後にこのトークンを自動的に再検証します。

コンポーネントに v-model を設定することで、検証トークンにアクセスできます。その後、トークンをフォームの応答と一緒に明示的または自動的に送信します (Cloudflare は cf-turnstile-response という名前の非表示のフォーム要素をフォームに追加します)。サーバー側でトークンを検証するには、Nitro サーバールートで自動インポートされる verifyTurnstileToken ユーティリティを使用できます。

Turnstile トークンは、verifyTurnstileToken を介して CloudFlare で処理された後は有効ではなくなります。サブミッションフォームなど、複数回検証が必要になる可能性のあるコンポーネントで @nuxtjs/turnstile を使用している場合は、サブミッションごとにトークンを再生成する必要があります。トークンを手動で再生成するには、@nuxtjs/turnstile はテンプレート参照を介して reset 関数を直接公開しています。

例:

<template>
  <NuxtTurnstile ref="turnstile" />
  <button @click="turnstile.reset()">Reset token in template</button>
  <button @click="reset()">Reset token from handler</button>
</template>

<script setup>
  // you can call this template ref anything
  const turnstile = ref()

  function reset() {
    turnstile.value?.reset()
  }
</script>

サーバー

生成された検証エンドポイントを使用するか、インポートされたヘルパーメソッドを使用できます

エンドポイントを使用した例:

最初にエンドポイントの生成をオンにします

export default defineNuxtConfig({
  // ...
  turnstile: {
    siteKey: '<your-site-key>',
    addValidateEndpoint: true
  },
})

これで、クライアントから /_turnstile/validate でエンドポイントを呼び出してトークンを検証できます。

カスタムエンドポイントとヘルパーメソッドを使用した例:

// server/api/validateTurnstile.ts

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

  if (!token) {
    throw createError({
      statusCode: 422,
      statusMessage: 'Token not provided.',
    })
  }

  return await verifyTurnstileToken(token)
})