@gkcaptcha/next

Next.js integration for gkCAPTCHA. Provides a Client Component and a Server Action helper.

Requirements

• Next.js >= 14
• React >= 18

Installation

npm install @gkcaptcha/next

Environment Variables

Add to .env.local:

GKCAPTCHA_SITE_KEY=pk_live_...
GKCAPTCHA_SECRET_KEY=sk_live_...
# Optional: override API URL (defaults to https://gkcaptcha.gatekeeper.sa)
# GKCAPTCHA_API_URL=https://gkcaptcha.gatekeeper.sa

Quickstart

Client Component

// app/login/page.tsx
'use client'
import { GkCaptcha } from '@gkcaptcha/next'

export default function LoginPage() {
  return (
    <form action={loginAction}>
      <GkCaptcha
        siteKey={process.env.NEXT_PUBLIC_GKCAPTCHA_SITE_KEY!}
      />
      {/* Auto-injects <input name="gk-captcha-token"> when CAPTCHA passes */}
      <button type="submit">Login</button>
    </form>
  )
}

Server Action

// app/actions/login.ts
'use server'
import { verifyCaptchaToken } from '@gkcaptcha/next/server'

export async function loginAction(formData: FormData) {
  const token = formData.get('gk-captcha-token') as string
  const result = await verifyCaptchaToken(token)

  if (!result.success) {
    return { error: 'CAPTCHA verification failed' }
  }

  // Proceed with login...
}

API Route

// app/api/auth/route.ts
import { verifyCaptchaToken } from '@gkcaptcha/next/server'

export async function POST(request: Request) {
  const body = await request.json()
  const result = await verifyCaptchaToken(body.captchaToken)

  if (!result.success) {
    return Response.json({ error: 'CAPTCHA failed' }, { status: 403 })
  }

  // Proceed...
}

Import Paths

| Import | Use In | Contains | |--------|--------|---------| | @gkcaptcha/next | Client Components | GkCaptcha, useGkCaptcha | | @gkcaptcha/next/server | Server Actions, API Routes | verifyCaptchaToken |

Never import from @gkcaptcha/next/server in a Client Component. It reads server-only env vars.

Props

See @gkcaptcha/react README for the full prop table — GkCaptcha has the same API.