Forms reference — Goeboek Next.js
Goeboek for Next.js has three forms, each posting to a server action in src/lib/actions.ts:
| Form | Where | Server action | form in the payload |
Fields (name → label) |
Required |
|---|---|---|---|---|---|
| Contact | Contact page | submitContact |
contact |
name Name, email Email, message Message |
name, email |
| Schedule tour | every property page | submitTour |
tour |
propertyId Property ID, propertyName Property Name (both filled in from the property), name Name, email Email, phone Phone, message Message |
propertyId, propertyName, name, email, phone |
| Add property | Add property page | submitProperty |
property |
name, email, phone, propertyName, location and category (radios), for (Sell / Rent), price, duration (/Days, /Months, /Years), size, bedrooms, bathrooms, floor, additionalSpace, furnishing, ceilingHeight, constructionYear, renovation (dates as YYYY-MM-DD), heating, airCondition, fireplace, elevator, ventilation, intercom, windowType, cableTv, wifi (Yes / No or text), message |
the personal fields, propertyName, for, price, duration and the details but renovation |
<Form> (design system) → server action (src/lib/actions.ts) → deliver() → provider(s) chosen in FORM_PROVIDERThe forms, their states, the e-mail check and the spam honeypot work out of the box. The button shows the visitor’s
progress: “Thank you” when it worked (the fields are cleared) and “Something went wrong” when it didn’t (what was typed
stays, so the visitor can try again). The tour and Add property forms then open their thank-you pages
(/success-scheduled, /success-add-property), as Framer does. Where the submissions go is a setting, not code.
1. Pick a provider
Section titled “1. Pick a provider”Copy .env.example to .env.local (or add the variables in your host, e.g. Vercel → Settings → Environment Variables)
and set FORM_PROVIDER. It applies to all three forms. Restart npm run dev after changing it.
FORM_PROVIDER |
What happens | Variables |
|---|---|---|
console (default) |
Printed to the server log. For development. | — |
webhook |
Posted as JSON to a URL — Zapier, Make, n8n, Pipedream, Formspree, Slack workflow, your own API. | FORM_WEBHOOK_URL, optional FORM_WEBHOOK_SECRET (sent as Authorization: Bearer …) |
mailchimp |
Sender added or updated in an audience, tagged with the form, the rest saved as a note. | MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID, optional MAILCHIMP_STATUS |
resend |
Emailed to you; replying answers the sender. | RESEND_API_KEY, FORM_EMAIL_TO, FORM_EMAIL_FROM |
Use several at once with a comma: FORM_PROVIDER=resend,mailchimp emails you and adds the contact to Mailchimp.
If any of them fails, the visitor sees “Something went wrong” (their input stays in the form) and the reason is logged on
the server. The providers run at the same time, so when one fails the others have usually delivered already: sending
again can duplicate. Each submission carries the form’s name (form) and its title (title: “New contact enquiry”,
“New tour request”, “New property submission” — the notification of each form’s copy).
The variables of .env.example
Section titled “The variables of .env.example”| Variable | For | Needed | What it is |
|---|---|---|---|
FORM_PROVIDER |
all | no (console when missing) |
console, webhook, mailchimp, resend, or several, separated by commas |
FORM_WEBHOOK_URL |
webhook | yes | The address that receives the POST |
FORM_WEBHOOK_SECRET |
webhook | no | Sent as Authorization: Bearer <secret>; leave it empty to send no header |
MAILCHIMP_API_KEY |
mailchimp | yes | Ends in your data center, e.g. …-us21 |
MAILCHIMP_AUDIENCE_ID |
mailchimp | yes | The audience that receives the contacts |
MAILCHIMP_STATUS |
mailchimp | no (transactional) |
The status of a new contact: transactional, pending or subscribed |
RESEND_API_KEY |
resend | yes | Your Resend API key |
FORM_EMAIL_TO |
resend | yes | The recipient, or several separated by commas |
FORM_EMAIL_FROM |
resend | yes | A sender on a domain verified in Resend, e.g. Javier Martinez <forms@yourdomain.com> |
A provider that needs a variable and doesn’t find it stops that submission with Missing environment variable <NAME> (see .env.example) in the server log; a name in FORM_PROVIDER that doesn’t exist does the same with
Unknown FORM_PROVIDER "<name>". The visitor sees “Something went wrong” in both cases.
What each provider receives
Section titled “What each provider receives”console:[forms] <title>followed by the submitted values (data) as an object, for example[forms] New tour request { propertyId: '55W886', propertyName: 'South Sunlight Apartment', name: 'Jane Smith', … }. In development it shows in the terminal that runsnpm run dev; on a host, in its logs.webhook: onePOSTof JSON (Content-Type: application/json) holding the whole submission, as in the payload below. An answer that isn’t a success is an error.mailchimp: three calls. The sender is added or updated in the audience (email, in lower case;name→FNAME,phone→PHONEwhen filled in;MAILCHIMP_STATUSis the status of a new contact only), tagged with the form’s title, and a note is added to the profile: the title, then one “Label: value” line for each field that was filled in.resend: one e-mail fromFORM_EMAIL_FROMtoFORM_EMAIL_TO. The subject is the title followed by the sender’s name (“New tour request — Jane Smith”), the reply address is the sender’s e-mail, and the text is one “Label: value” line for each field that was filled in, then the time it was sent.
Mailchimp notes
Section titled “Mailchimp notes”- API key: Profile → Extras → API keys. It ends in your data center (
…-us21); nothing else to configure. - Audience ID: Audience → Settings → Audience name and defaults.
- Consent: new contacts are added as
transactional— they can receive replies, not campaigns. Usependingto send a double opt-in email, orsubscribedonly if the form asks for marketing consent. None of the three forms asks for it. - Merge fields:
mergeFieldsat the top ofproviders/mailchimp.tsmaps the field names to a new audience’s default tags (FNAME,LNAME,PHONE). Change it if your audience uses other tags.
Webhook payload
Section titled “Webhook payload”The Schedule tour form of South Sunlight Apartment:
{ "form": "tour", "title": "New tour request", "submittedAt": "2026-11-02T10:48:23.256Z", "data": { "propertyId": "55W886", "propertyName": "South Sunlight Apartment", "name": "Jane Smith", "email": "jane@example.com", "phone": "+1 555 000 0000", "message": "Could I see it on Saturday morning?" }, "labels": { "propertyId": "Property ID", "propertyName": "Property Name", "name": "Name", "email": "Email", "phone": "Phone", "message": "Message" }}Add property sends every field of the page, in its order (abridged):
{ "form": "property", "title": "New property submission", "submittedAt": "2026-11-02T10:52:07.118Z", "data": { "name": "Jane Smith", "email": "jane@example.com", "phone": "+1 555 000 0000", "propertyName": "Garden Loft", "location": "Queens", "category": "Houses", "for": "Rent", "price": "2400", "duration": "/Months", "size": "90", "bedrooms": "2", "bathrooms": "1", "constructionYear": "2007-07-01", "renovation": "", "airCondition": "Yes", "…": "…", "message": "" }, "labels": { "name": "Name", "propertyName": "Property Name", "duration": "Duration", "…": "…" }}data has a key for every field, in the order of the form, and labels the label of each. A field left empty is ""
(a radio group nobody picked, a select left on its placeholder). The contact form sends name, email and message.
2. Spam: the honeypot
Section titled “2. Spam: the honeypot”Each form carries a hidden text field named fax (honeypotField in
src/design-system/components/forms/form-state.ts): it is out of sight and out of the tab order, a person never fills
it, and bots usually do. deliver() looks at it first: when it holds anything, the visitor is shown “Thank you” and
nothing is sent, so the bot moves on. Keep it as it is, and don’t give a real field the name fax.
3. The checks and the server action
Section titled “3. The checks and the server action”In the browser, <Form> checks the fields before sending: when a required field is empty or the e-mail isn’t an e-mail
address, the first failing field gets the focus and every failing field is marked until it is changed. Without
JavaScript the form still posts and the browser’s own check runs.
The server actions check again, since a browser can be bypassed: each one (submitContact, submitTour,
submitProperty) lists the fields of its form from the page copy, with their required flags, and calls
deliver(data, { form, title, fields, required }) from src/lib/forms/deliver.ts, which:
- drops the submission if the honeypot is filled;
- reads each listed field from the submitted data (trimmed);
- returns the error state when a required field is empty;
- builds the submission (
form,title,submittedAt,data,labels) and gives it to every provider named inFORM_PROVIDER; - returns the success state, or the error state with the reason logged (
[forms] <title> could not be delivered).
4. Add your own provider (HubSpot, Brevo, Airtable, a database…)
Section titled “4. Add your own provider (HubSpot, Brevo, Airtable, a database…)”-
Create
src/lib/forms/providers/<name>.ts:import { env, valueOf, type FormProvider } from "../types";export const brevoProvider: FormProvider = {name: "brevo",async send(submission) {const response = await fetch("https://api.brevo.com/v3/contacts", {method: "POST",headers: { "api-key": env("BREVO_API_KEY"), "Content-Type": "application/json" },body: JSON.stringify({email: valueOf(submission, "email"),attributes: { FIRSTNAME: valueOf(submission, "first name"), LASTNAME: valueOf(submission, "last name") },updateEnabled: true,}),});if (!response.ok) throw new Error(`Brevo responded ${response.status}: ${await response.text()}`);},}; -
Register it in
providers/index.ts(brevo: brevoProvider). -
Set
FORM_PROVIDER=brevoand its variables in.env.example/ your host.
Helpers from types.ts: valueOf(submission, name) returns one field as text (the name is matched ignoring case, so
"email" finds Email), toLines(submission) returns "Label: value" lines for every filled field, and env(name)
reads a required variable with a clear error. All three forms always deliver an email.
5. Change the form
Section titled “5. Change the form”- Fields and labels live in the copy (edited in
content/pages/*.jsonin the workspace, then synced): the contact form incontact.json→form, Schedule tour inproperty.json→tour, Add property inadd-property.json→form.nameis the key providers receive,labelis what people read above the field (and what the notification shows),placeholderis what the empty field shows,typepicks the control (text,email,tel,number,date,textarea; a field withoptionsis a select, Add property’s Location and Category are radios),requiredmakes the field checked before sending. The button’s three texts (submit,success,error), the notification title and the page a form opens once sent (redirect) are there too. - Required fields come from the same
requiredflags: the server action checks them again before it sends anything. - A new field: add it to the copy, then to the form’s section (
src/components/sections/TourForm.tsx,AddPropertyForm.tsx) and to its list insrc/lib/actions.ts, so it is placed and delivered. - A new form: lay it out with
<Form>and<FormField>, add a server action next to the others insrc/lib/actions.ts(“use server”) that callsdeliver(data, { form, title, fields, required }), and add the form name toFormKindintypes.ts.