Astro Forms

Astro Forms Skill

Server-side form handling for lead generation sites on Cloudflare Workers.

Scope

This skill covers the backend pipeline: validation → spam check → storage → email → redirect → analytics. For form UI components, field layout, and styling see the project's frontend patterns. The one exception is modifiers.md which documents common form layout variants for reference.

Implementation Sequence

When building a form, follow this order:

1. Define the schema — references/schemas.md → copy + adapt Zod schema
2. Copy boilerplate — assets/boilerplate/lib/ → into src/lib/forms/
3. Configure Worker — wrangler.toml with KV binding, wrangler secret put for all secrets
4. Set up Google Sheet — create service account, share sheet, add column headers (row 1)
5. Wire frontend — form posts to /api/submit, includes Turnstile + honeypot + hidden fields
6. Test locally — wrangler dev, submit form, check email + Sheets
7. Deploy — wrangler deploy
8. Audit — run through Conversion Verdict below

Required Policy (non-negotiable)

These apply regardless of tech stack choice:

Recommended Stack

Canonical Submission Schema

One naming convention everywhere: camelCase in TypeScript, maps to storage columns.

type FormSubmission = {
  leadId: string;          // Generated UUID
  formId: string;          // e.g. "contact-form"
  sourcePage: string;      // URL path where submitted
  submittedAt: string;     // ISO 8601 datetime
  name: string;
  email: string;
  phone?: string;
  message?: string;
  ipHash: string;          // SHA-256 of IP + daily salt, never raw IP
  userAgent?: string;
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  referrer?: string;
};

All boilerplate, schemas, and references use these field names.

Primary Conversion Declaration

One form per page is THE conversion.

primary_conversion:
  type: form
  id: "contact-form"
  page: "/contact"

All other forms on the page are secondary (newsletter, etc.).

Progressive Disclosure

Personal data only AFTER value is established.

Asking email on step 1 is acceptable on high-intent pages (e.g. /contact) but should be avoided on exploratory pages. Use judgement, not a blanket rule.

Spam Protection

All four layers recommended. Minimum two required.

Failure Policy

What happens when part of the pipeline fails:

Core principle: never lose a valid lead because a secondary system failed. Email and Sheets failures are logged and alerted, but the user sees success and the lead data is preserved in logs at minimum.

Conversion Verdict

Locale Support

The skill supports both en-GB and hu-HU locales. Locale affects:

• Zod validation error messages
• Phone number regex pattern
• Email template language
• Postcode format and lookup endpoint

Default locale is en-GB (UK service businesses). See references/schemas.md for locale-specific validation.

Environment Variables

RESEND_API_KEY=re_xxxxx
BREVO_API_KEY=xkeysib-xxxxx
GOOGLE_SERVICE_ACCOUNT_EMAIL=forms@project.iam.gserviceaccount.com
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
GOOGLE_SHEET_ID=1aBcDeFgHiJkLmNoPqRsTuVwXyZ
TURNSTILE_SITE_KEY=0x...       # Frontend only
TURNSTILE_SECRET_KEY=0x...     # Backend only
IP_HASH_SALT=random-daily-salt
SITE_URL=https://example.com

Critical: all backend env vars are accessed via the env parameter (Workers binding), NOT import.meta.env. The submit.ts handler receives env from the Workers fetch(request, env, ctx) signature. Every boilerplate helper accepts env as a parameter.

If the form runs inside an Astro SSR API route (src/pages/api/*.ts): use import { env } from 'cloudflare:workers' at the top of each handler file. Astro.locals.runtime.env was removed in Astro v6 and throws Worker unhandled exception at runtime. See astro-v6-runtime.md for the full writeup (covers try/catch, --keep-vars, trailing slash, Turnstile hostname allowlist).

For Google Sheets: create a service account in Google Cloud Console, download the JSON key, share the target spreadsheet with the service account email address, then set GOOGLE_SERVICE_ACCOUNT_EMAIL, GOOGLE_PRIVATE_KEY, and GOOGLE_SHEET_ID as secrets.

References

• schemas.md — Zod schemas (EN/HU), canonical types
• email.md — Email templates and delivery rules
• resend-setup.md — Resend DNS + account setup guide
• cloudflare-setup.md — Turnstile, KV, Workers
• astro-v6-runtime.md — Astro v6 env access, try/catch pattern, --keep-vars, trailing slash, Turnstile hostnames
• modifiers.md — Form layout variants (UI reference)
• schema-cta.md — CTA structure and tracking

Integration with Tracking Skill

This skill handles the server-side pipeline (validation, storage, email). The soborbo-tracking package (now in github.com/Soborbo/Serverside → soborbo-tracking/, moved out of this repo on 2026-07-21) handles client-side conversion tracking (dataLayer, Meta CAPI beacon). They work together:

User clicks Submit
  → <TrackedForm> intercepts (tracking skill)
  → trackLeadSubmit() fires:
      • pushes lead_submit to dataLayer (GTM → GA4, Google Ads)
      • sends beacon to /api/track (Meta CAPI)
      • populates hidden fields (event_id, gclid, UTM)
  → form.submit() fires (native POST)
  → /api/submit receives the POST (this skill)
      • validates, dedup, Sheets, email
      • event_id links the two systems

Key integration point: The event_id hidden field connects the client-side conversion event with the server-side lead record. Both the Meta CAPI event and the Google Sheets row contain the same event_id, enabling deduplication and attribution reconciliation.

What goes where:

• <TrackedForm> wraps the HTML form (tracking skill component)
• /api/track receives the Meta CAPI beacon (tracking skill endpoint)
• /api/submit receives the form POST (this skill's endpoint)

Boilerplate

Copy assets/boilerplate/lib/ → src/lib/forms/. The key file is submit.ts which exports a Workers-compatible fetch handler and wires together all other modules. Use ctx.waitUntil() for non-blocking Sheets saves.

Definition of Done

• Schema defined with correct locale
• submit.ts handler wired up (or Astro API route using import { env } from 'cloudflare:workers')
• Every API handler wrapped in a top-level try/catch that logs SRV-FUNC-001
• Env vars configured (local + production)
• Deploy command uses --keep-vars (Workers Builds → Build configuration)
• Turnstile site key set at build time and all hostnames listed in Turnstile allowed list
• Frontend fetches use trailing slash if trailingSlash: 'always'
• CookieYes consent banner configured
• Spam protection: minimum 2 layers active
• Duplicate protection active
• Customer confirmation email sends
• Business notification email sends
• Thank-you redirect works
• GTM event fires
• User input escaped in email HTML
• conversion_verdict = PASS