Home / Посібники / Інтеграція бекенда форми Next.js (маршрутизатор програми та дії сервера)
ПОСІБНИК З ІНТЕГРАЦІЇ · FRONTEND & NEXT.JS

Інтеграція бекенда форми Next.js (маршрутизатор програми та дії сервера)

Повний посібник із впровадження TypeScript і React для обробки контактних форм у Next.js 14/15 за допомогою кінцевих точок Lugatu та дій сервера з нульовим доступом до облікових даних.

1. Архітектура маршрутизатора програми Next.js із діями сервера

Серверні дії Next.js виконуються виключно на сервері, що робить їх ідеальними для надсилання запитів за допомогою приватних ключів Lugatu API без розкриття секретів у пакетах клієнтів.

app/actions/contact.ts typescript
'use server';

export async function submitContact(prevState: any, formData: FormData) {
  // Silent rejection of automated bot submissions via honeypot trap
  const honeypot = (formData.get('_gotcha') as string) || '';
  if (honeypot) {
    return { success: true, error: null };
  }

  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name || !email || !message) {
    return { success: false, error: 'All fields are required.' };
  }

  const payload = {
    fields: { name, email, message },
  };

  try {
    const res = await fetch(`https://www.lugatu.com/api/v1/forms/${process.env.LUGATU_FORM_ID}/submissions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.LUGATU_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': crypto.randomUUID(),
      },
      body: JSON.stringify(payload),
    });

    if (!res.ok) {
      return { success: false, error: 'Failed to submit form.' };
    }

    return { success: true, error: null };
  } catch (err) {
    return { success: false, error: 'Network error occurred.' };
  }
}

2. Компонент форми на стороні клієнта зі станом завантаження

Підключіть свою серверну дію до клієнтського компонента React 19 / Next.js із доступними індикаторами завантаження.

components/ContactForm.tsx tsx
'use client';

import { useActionState } from 'react';
import { submitContact } from '@/app/actions/contact';

export function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, { success: false, error: null });

  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <div>
        <label className="block text-sm font-semibold mb-1">Name</label>
        <input name="name" required className="w-full border rounded-xl p-2.5" />
      </div>
      <div>
        <label className="block text-sm font-semibold mb-1">Email</label>
        <input type="email" name="email" required className="w-full border rounded-xl p-2.5" />
      </div>
      <div>
        <label className="block text-sm font-semibold mb-1">Message</label>
        <textarea name="message" rows={4} required className="w-full border rounded-xl p-2.5" />
      </div>

      <input type="text" name="_gotcha" style={{ display: 'none' }} tabIndex={-1} autoComplete="off" />

      <button type="submit" disabled={isPending} className="btn-primary-editorial w-full py-2.5">
        {isPending ? 'Sending...' : 'Send Message'}
      </button>

      {state.success && <p className="text-emerald-700 text-sm">Thank you! Your message was received.</p>}
      {state.error && <p className="text-red-700 text-sm">{state.error}</p>}
    </form>
  );
}

Інваріант безпеки та автентифікації

Інструкція з безпеки: ніколи не додавайте префікс LUGATU_API_KEY до NEXT_PUBLIC_. Тільки приватні змінні на стороні сервера можуть безпечно зберігати ваш живий ключ API.

Усунення несправностей і поширені помилки передавання

Запит на ключ API повертає 403 FORBIDDEN_BROWSER_ORIGIN

Ви здійснюєте виклик fetch() із коду браузера на стороні клієнта за допомогою ключа API. Перейдіть на дію сервера Next.js або використовуйте кінцеву точку публічної форми без ключа API.

Часті запитання

Чи можу я розгорнути це на сторінках Vercel або Cloudflare?

так Server Actions бездоганно працюють на безсерверних платформах і периферійних середовищах виконання, які підтримуються Next.js.

Готові створити кінцеву точку форми?

Почніть безкоштовно за лічені секунди. Кредитна картка не потрібна.

Почніть безкоштовно →