SiteOS Forms

Connect your Zod schemas to SiteOS Forms. Keep your existing validation, UI and form library. The SDK describes your forms for SiteOS and provides the version used when submitting answers.

Installation

pnpm add @siteoshq/forms zod

Compatibility

| Requirement | Supported | | ------------- | ----------------------------- | | Node.js | 22.12+ | | Zod | 4.x, including Zod Mini | | Module format | ESM | | SiteOS CLI | 2.45.0+ for form registration |

The SDK runs on the server and adds no code to the browser bundle. Its JavaScript is approximately 2.8 kB, or 0.9 kB minified and gzipped, excluding the Zod peer dependency.

Usage

Define your validation schema as usual:

// src/lib/validation.ts
import { z } from "zod";

export const contactSchema = z.object({
  name: z.string().trim().min(1),
  email: z.email(),
});

Reference it in a server-only registration file:

// siteos.forms.ts
import { createForm } from "@siteoshq/forms";
import { contactSchema } from "./src/lib/validation";

export const contact = createForm({
  formKey: "contact",
  name: "Contact",
  sourcePagePath: "/contact",
  schema: contactSchema,
  fields: {
    name: { label: "Name", displayRole: "primary" },
    email: { label: "Email", kind: "email", displayRole: "secondary" },
  },
});

export default [contact];

fields describes how answers appear in the SiteOS inbox. Include each schema field and mark one required field as primary. Validation rules stay in Zod. Browser components import the shared schema; the server imports the registration.

Register and submit

After connecting your project and configuring publication credentials, check and register the forms with the SiteOS CLI:

siteos forms definition check --source siteos.forms.ts --json
siteos forms deploy --source siteos.forms.ts --json

Publish schema or inbox metadata changes before deploying the updated website. UI-only changes need no publication. Your ordinary build command stays unchanged.

Your server validates incoming answers with contactSchema.safeParse or safeParseAsync, then sends the parsed output to the Forms submission API. Use contact.formKey and contact.contractVersion from the server-side registration in that request. The API key stays on the server.

SiteOS checks the submitted structure and supported validation rules. Custom Zod refinements and transforms run on your server. See the form contract guide for field metadata and supported output schemas.

License

MIT