Forms reference — Brickfolio Astro
Brickfolio for Astro has two forms: the contact form on Home (“Let’s Connect”, Form.astro, form contact) and the newsletter
box in the footer of every page (NewsletterForm.astro, form newsletter). They work in one of three ways, chosen with
environment variables (copy .env.example to .env, or set them in your host’s dashboard); no code changes.
| Form | Where | form in the payload |
Fields (name → label) |
Required |
|---|---|---|---|---|
| Contact | Home (#contact) |
contact |
First Name, Last Name, Email, Phone Number, Message |
all but Message (Email must look like an e-mail address) |
| Newsletter | every page (footer) | newsletter |
Email Email |
Email (must look like an e-mail address) |
| Mode | Set | Hosting | Where submissions go |
|---|---|---|---|
| Demo (default) | nothing | any static host | Nowhere: the button shows “Thank you” and the fields are logged in the browser console. |
| Static | PUBLIC_FORM_ENDPOINT |
any static host | Posted from the browser to a form service or webhook. |
| Server | PUBLIC_FORM_MODE=server + FORM_PROVIDER |
a host with an Astro adapter | Delivered by the site’s own route to console, webhook, Mailchimp or Resend. |
Every mode shows the same states on the button (a spinner while sending, then “Thank you” or “Something went wrong”) and
drops spam caught by the hidden honeypot field (fax). The contact form checks its fields first (the first empty or invalid
one gets the focus), resets on success and keeps what was typed on an error; the newsletter field clears once the answer is in.
The PUBLIC_ variables are read when the site is built: rebuild (or restart npm run dev) after changing them.
<Form> / <NewsletterForm> → browser: PUBLIC_FORM_ENDPOINT, or the demo → server mode: POST /api/forms/<form> → deliver() → provider(s) chosen in FORM_PROVIDERformEndpoint("contact") / formEndpoint("newsletter") in src/lib/forms/endpoint.ts decide where a form posts:
/api/forms/<form> in server mode, else PUBLIC_FORM_ENDPOINT, else nothing (demo mode). The browser parts are
src/design-system/scripts/form.ts and newsletter.ts; the forms’ definitions (fields, required, e-mail check) are in
src/lib/forms/definitions.ts.
1. Static mode: form services and webhooks
Section titled “1. Static mode: form services and webhooks”Set PUBLIC_FORM_ENDPOINT to the URL the service gives you. The form posts multipart/form-data with
Accept: application/json; the service must answer with a 2xx status, anything else shows “Something went wrong”.
| Service | PUBLIC_FORM_ENDPOINT |
Notes |
|---|---|---|
| Formspree | https://formspree.io/f/<form id> |
Emails you each submission. |
| Web3Forms | https://api.web3forms.com/submit |
Also set PUBLIC_FORM_ACCESS_KEY (sent as the hidden field access_key). |
| Getform, Basin | the form’s endpoint URL | |
| Zapier, Make, n8n, Pipedream | the webhook (“catch hook”) URL | Route submissions anywhere: Mailchimp, Google Sheets, Slack, a CRM. |
Fields sent: the fields above, plus form (contact or newsletter) and subject.
2. Server mode: your own route
Section titled “2. Server mode: your own route”- Add the adapter for your host:
npx astro add vercel(ornetlify,node, …). - Set
PUBLIC_FORM_MODE=serverand choose providers withFORM_PROVIDER.
The forms then post to POST /api/forms/contact and /api/forms/newsletter (src/lib/forms/route.ts, added by src/integrations/forms.ts; every other
page stays prerendered). Without an adapter the build stops with NoAdapterInstalled. Astro rejects cross-site posts to the
route. The route answers JSON: 200 { "status": "success" }, or 500 { "status": "error" } (404 unknown form, 400 not
form data).
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, your own API. | FORM_WEBHOOK_URL, optional FORM_WEBHOOK_SECRET (sent as Authorization: Bearer …) |
mailchimp |
Subscriber added or updated in an audience and tagged with the form. | MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID, optional MAILCHIMP_STATUS |
resend |
Emailed to you. | RESEND_API_KEY, FORM_EMAIL_TO, FORM_EMAIL_FROM |
Use several with a comma (FORM_PROVIDER=resend,mailchimp). If one fails the visitor sees the error state and the reason is
logged on the server. A provider that needs a variable and doesn’t find it stops the submission with Missing environment variable <NAME> (see .env.example). Add your own provider in src/lib/forms/providers/index.ts.