Enquiries plugin
Add contact and booking forms defined in code, with spam protection and email notification, using @kitcms/plugin-enquiries.
This page covers @kitcms/plugin-enquiries: defining forms, the submissions collection, spam protection, the Svelte component and the security model.
pnpm add @kitcms/plugin-enquiriesForms are defined in code, so editors cannot change what a form asks. Submissions are stored in a locked-down collection. Staff can be notified by email.
Define forms
import { defineConfig } from '@kitcms/core';
import { enquiries } from '@kitcms/plugin-enquiries';
export default defineConfig({
email: { from: { address: 'no-reply@example.com', name: 'Acme' } },
collections: [/* ... */],
plugins: [
enquiries({
forms: {
contact: {
label: 'Contact form',
notify: ['hello@example.com'],
subject: 'Message from {field:name}',
replyTo: 'email',
fields: {
name: { type: 'text', required: true, maxLength: 80 },
email: { type: 'email', required: true },
message: { type: 'textarea', required: true },
consent: { type: 'checkbox', required: true },
},
},
},
}),
],
});The plugin adds a submissions collection. Run pnpm db:generate <name> and pnpm db:migrate.
| Option | Default | What it does |
|---|---|---|
forms |
required | Form name (lowercase letters, digits and -, starting with a letter) mapped to { label, fields, notify?, subject?, replyTo? }. notify is a list of addresses or a function returning one. |
collection |
'submissions' |
Slug of the submissions collection. |
turnstile |
off | { siteKey, secret? }. siteKey is a string or a function. secret is the name of the Worker secret. Default TURNSTILE_SECRET. |
rateLimit |
{ max: 5, window: 600 } |
Per IP address, counted in D1. window is in seconds. |
entitlement |
none | Gate the plugin and its collection behind an add-on. |
Field types
text (max 200), textarea (max 5000), email, number (min, max, integer), date (YYYY-MM-DD), select (options) and checkbox (required means it must be checked). Unknown keys in a submission are dropped.
subject accepts {form} (the form label) and {field:name}. Line breaks are removed from values.
Set email in the config and add the send_email binding. Without them, submissions are stored but not emailed. See Email. An email failure never fails the submission.
notify can be a function of the Worker env and the site's content, for example to email the address in a settings global. It runs for each submission and returns a list. Addresses that are not valid are skipped, and with none left the submission is stored without a notification:
notify: async ({ cms }) => {
const site = await cms.findGlobal('site');
const email = site?.contactEmail;
return typeof email === 'string' && email ? [email] : [];
},The same goes for turnstile.siteKey: siteKey: ({ env }) => String(env.TURNSTILE_SITE_KEY). See Per-request values.
Turnstile
For Cloudflare Turnstile, pass the site key and store the secret:
pnpm exec wrangler secret put TURNSTILE_SECRETLocally, put TURNSTILE_SECRET=1x0000000000000000000000000000000AA in .dev.vars and use the site key 1x00000000000000000000AA. Those are Cloudflare's always-pass test keys. If Turnstile is configured but the secret is missing, submissions are rejected with a 500 (fail closed).
On the site
<script lang="ts">
import { page } from '$app/state';
import { EnquiryForm, fieldError } from '@kitcms/plugin-enquiries/svelte';
</script>
<EnquiryForm form="contact" page={page.url.pathname}>
{#snippet children(enquiry)}
<label for="name">Name</label>
<input
id="name"
name="name"
required
aria-invalid={fieldError(enquiry, 'name') ? 'true' : undefined}
aria-describedby={fieldError(enquiry, 'name') ? 'name-error' : undefined}
/>
{#if fieldError(enquiry, 'name')}<p id="name-error">{fieldError(enquiry, 'name')}</p>{/if}
<label for="email">Email</label>
<input id="email" name="email" type="email" required />
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<label><input type="checkbox" name="consent" required /> I agree to be contacted</label>
<button disabled={enquiry.status === 'submitting'}>Send</button>
{/snippet}
</EnquiryForm>The component renders the <form method="post">, a hidden honeypot, the Turnstile widget and an aria-live status region. You render the fields. Props: form, action (default /api/plugins/enquiries/submit/<form>; pass a base-prefixed URL when your app has a base path), turnstileSiteKey, page and class.
Without JavaScript, the form posts normally and the server answers 303 back to page (or a same-origin Referer) with ?enquiry=sent or ?enquiry=error&fields=name,email.
From any client: POST /api/plugins/enquiries/submit/<form> with application/json (the Turnstile token as turnstileToken) or a form body (cf-turnstile-response). Same-origin only. Success is { ok: true, message }. Errors are 400 { error, errors: [{ path, message }] }. GET /api/plugins/enquiries/forms/<form> returns the public definition of a form.
Security
- Only the endpoint can create submissions.
read,updateanddeleteare for admins (role === 'admin'), andcreateis denied for everyone through REST, RPC and the Local API. Admins can change onlystatus. - No IP addresses are stored. The IP is used for rate limiting and Turnstile.
- A filled honeypot gets a success response and nothing is stored.
- Strict validation against the form in code. No file uploads. Bodies are capped at 16 KiB.
- Cross-origin POSTs are refused by core. The redirect target for no-JavaScript posts must be a same-origin relative path, otherwise
/. - In email, user values are HTML-escaped, and neither the subject nor the reply-to can inject headers.