Forms

A generated site has no form handler of its own, and you should not write one. The kit has a forms module: one definition file per form, one shared route that serves every form, and a Form component for pages. The module validates input with the same schema in the browser and on the server, hides a trap field from people, limits how often one address can send, optionally checks Cloudflare Turnstile, and sends the message by mail.

A form needs server code, so adding the first form moves a static site to the server hosting model. On a site with a separate backend it does not: the backend serves the form instead. Read Choose a hosting model first if you are not sure which model your site is in.

What you’ll do

1. Run npx mdlake add-form to create the form, its page and its settings.
2. Edit the form definition to match what the client needs.
3. Set the recipient and the mail settings.
4. Try the form locally, with and without JavaScript.

Before you start

• A site scaffolded with the builder, with npm install done.
• The developer or client has approved that the site becomes a server site (an App Service instead of the free Static Web Apps tier). The add-form skill asks for this approval first.
• Decide the recipient address. It will live in an environment variable, never in code.

Add a form

Run this in the site folder:

npx mdlake add-form contact --route /contact/ --turnstile

You can also ask Claude Code to run the add-form skill. It asks you for the same choices and stops for approval before it commits anything.

The command writes these files and never overwrites one that exists:

It ends by printing the secrets and settings you have to set where the site runs. Nothing secret goes into the repository or the lake.

On a site with a separate backend

On a split site, add-form writes src/forms/<name>.ts and the page, but no [name].ts route and no @astrojs/node. The backend must serve the form too. The command prints the exact line to add. npm run check fails until it is there. See Forms on a split site.

The form definition

This is what the command writes for a form called contact with --turnstile:

import { defineForm, z } from '@mdlake/site-kit/forms'

export default defineForm({
  schema: z.object({
    name: z.string().min(1, 'Enter your name').max(120, 'Use at most 120 characters'),
    email: z.email('Enter a valid email address').max(200),
    message: z.string().min(10, 'Write a few words more').max(4000, 'Use at most 4000 characters'),
  }),
  fields: [
    { name: 'name', label: 'Your name', autocomplete: 'name' },
    { name: 'email', label: 'Email address', type: 'email', autocomplete: 'email' },
    { name: 'message', label: 'Message', type: 'textarea' },
  ],
  recipientEnv: 'CONTACT_FORM_TO',
  subject: 'New message from the website',
  success: { message: 'Thank you. Your message has been sent.' },
  replyTo: 'email',
  turnstile: true,
})

The file is site-owned: edit it freely. The schema says what is valid. fields says what to draw. The labels, the button text and the messages are site chrome and belong in this file, not in the lake. The one thing that must never be in this file is the recipient address: recipientEnv names the variable.

Options

Field options

An example with an optional field, a choice and a consent checkbox:

import { defineForm, z } from '@mdlake/site-kit/forms'

export default defineForm({
  schema: z.object({
    name: z.string().min(1, 'Enter your name'),
    email: z.email('Enter a valid email address'),
    topic: z.enum(['sales', 'support'], 'Choose a topic'),
    phone: z.string().max(40).optional(),
    consent: z.literal(true, 'Please accept that we store your message'),
    message: z.string().min(10, 'Write a few words more'),
  }),
  fields: [
    { name: 'name', label: 'Your name', autocomplete: 'name' },
    { name: 'email', label: 'Email address', type: 'email', autocomplete: 'email' },
    { name: 'topic', label: 'Topic', type: 'select', options: [{ value: 'sales', label: 'Sales' }, { value: 'support', label: 'Support' }] },
    { name: 'phone', label: 'Phone (optional)', type: 'tel', autocomplete: 'tel' },
    { name: 'message', label: 'Message', type: 'textarea', help: 'The more you tell us, the better we can help.' },
    { name: 'consent', label: 'I accept that you store my message', type: 'checkbox', required: true },
  ],
  recipientEnv: 'CONTACT_FORM_TO',
  subject: 'New message from the website',
  success: { message: 'Thank you. We will answer within two working days.', page: '/thanks/' },
  replyTo: 'email',
})

What defineForm checks

defineForm runs when the dev server or the build loads the file. It throws with a list of problems, so a broken form is never found by a visitor:

• the schema has a key that no field describes, or a field is not a key of the schema, or a field is listed twice;
• recipientEnv is not the name of a variable (for example you wrote an address);
• success.page does not start with a single /;
• replyTo is not a field;
• a field has the same name as the honeypot;
• rateLimit has a max or windowSeconds below 1;
• a select has no options.

The page

The generated page is a normal Astro page:

---
import Form from '@mdlake/site-kit/components/modules/Form.astro'
import Layout from '@mdlake/site-kit/layouts/Layout.astro'
---

<Layout title="Contact">
  <Form name="contact" heading="Contact" level={1} />
</Layout>

You can put the Form component on any hand-written page. The page is yours: change the layout, add text around it, link it from the navigation when the client asks. To render the form differently for the whole site, override the module in site.config.ts (modules: { form: './src/components/MyForm.astro' }). See Custom components.

What happens when someone sends the form

The browser posts to /api/forms/<name>/. The trailing slash is part of the address: the site uses trailing slashes everywhere, and a redirect would turn the POST into a GET. The server runs these steps in order and stops at the first that fails:

1. Rate limit. Too many recent submissions from this address answer 429 with a Retry-After header.
2. Body. The body must be a normal form post (application/x-www-form-urlencoded or multipart/form-data) or JSON, and at most 64 KB.
3. Honeypot. Anything in the trap field gets a success answer and nothing is sent.
4. Validation. The schema checks the values. Invalid input answers 422 with one message per field.
5. Turnstile, if the form asks for it.
6. Mail. The message is sent through the mail provider. See Mail.
7. Answer. JSON for a fetch call, or a 303 redirect for a plain form post.

Answers

A client that sends Accept: application/json or a JSON body gets JSON. Any other client gets the same status with a small HTML page that says what went wrong and links back to the form.

Honeypot

The form contains a text field named company_website (or the name you set) that no person sees. It is moved off screen, hidden from assistive technology and skipped by the tab key. A script that fills every field fills it too, and gets a success answer while nothing is sent. The hit still counts against the rate limit.

Rate limit

The limit is per form and per client address. The counters live in the memory of one server process. Behind a scaled-out App Service plan, each instance counts for itself, so the real limit is max times the number of instances, and a restart forgets everything. That is enough to stop a script from filling a mailbox. It is not a security boundary.

The client address comes from the X-Forwarded-For header, counting from the right. TRUSTED_PROXY_HOPS says how many proxies you trust (default 1). Never trust the left side of that header: the visitor can forge it. The generated Bicep sets TRUSTED_PROXY_HOPS to 2 for the split model, where Static Web Apps sits in front of the App Service.

Without JavaScript

The form is rendered on the server as a plain <form method="post" action="/api/forms/<name>/">, so it works when JavaScript is off or fails to load:

• A valid post redirects (303) to success.page, or back to the page the visitor came from with #form-<name>-sent added. The page shows the success message when that anchor is the target.
• An invalid post shows a small page with the problems and a link back to the form.

With JavaScript, the form validates in the browser with the same schema, shows the errors next to the fields, moves focus to the first invalid field, posts with fetch, and shows the success message in place. Turnstile is the one feature that needs JavaScript.

Settings

Add the values to .env locally (copy .env.example first) and to the hosting environment for deployment. The names are the same everywhere.

Try it

1. Copy .env.example to .env and set MAIL_PROVIDER=log and your recipient variable.

   PowerShell

   Copy-Item .env.example .env

   Bash

   cp .env.example .env

2. Run npm run dev and open the form page. Send a message. The dev server prints the mail instead of sending it:

   [mdlake mail:log] to=owner@example.com from=forms@localhost subject="New message from the website" reply-to=anna@example.com
   Your name: Anna
   ...
   [mdlake mail:log] end

3. Turn JavaScript off in the browser’s developer tools and send again. The page should reload with the success message.

4. Send the form with the name left empty. You see the field error next to the field, and no mail is sent.

5. Test the endpoint directly. The answer for an invalid body is a 422 with the message per field (-SkipHttpErrorCheck needs PowerShell 7):

   Bash

   curl -i -X POST http://localhost:4321/api/forms/contact/ \
     -H "content-type: application/json" \
     -d '{"name":"","email":"x","message":"short"}'

   PowerShell

   Invoke-WebRequest -Method Post -Uri http://localhost:4321/api/forms/contact/ `
     -ContentType 'application/json' -Body '{"name":"","email":"x","message":"short"}' `
     -SkipHttpErrorCheck

6. Run npm run check. It fails until the pipelines and Bicep are written for the server model. Run the setup-hosting skill, or npx mdlake hosting init --ci github (see Azure and Bicep).

What can go wrong

What’s next

• Mail to send real mail with Resend.
• Turnstile to add a bot check.
• Azure and Bicep to deploy the server.