marcomuser
Conformal
Type-safe form submissions for the modern web.
Conformal helps you work with native FormData. It solves two major pain points:
- ✅ Strongly typed FormData parsing – Turn native
FormDatainto real objects with full TypeScript inference (nested objects and arrays with dot/bracket notation). - ✅ Canonical submission flow – A single
Submissionobject that preserves raw input, separates field vs. form errors, and standardizes the success/error states.
Works everywhere: In browsers, Node.js, and edge runtimes with React, Vue, Svelte, or vanilla JavaScript.
Table of Contents
Getting Started
Install Conformal via npm or the package manager of your choice:
npm install conformalHere's a quick example showing how Conformal handles form validation with a user registration form:
import { parseFormData } from "conformal";
import * as z from "zod";
// Tip: Use conformal's coerce functions for form input preprocessing
const schema = z.object({
name: z.string().min(2, "Name must be at least 2 characters"),
email: z.email("Invalid email address"),
age: z.coerce.number().min(18, "Must be at least 18 years old"),
acceptTerms: z.coerce.boolean(),
});
// In your form action or handler
const result = parseFormData(schema, formData);
const submission = result.submission();
if (submission.status === "success") {
// submission.value is fully typed: { name: string, email: string, age: number, acceptTerms: boolean }
console.log("User registered:", submission.value);
} else {
// submission.fieldErrors contains validation errors: { email: ["Invalid email address"] }
console.log("Validation errors:", submission.fieldErrors);
// submission.input preserves the raw user input for re-display
console.log("User input:", submission.input);
}That's it! Conformal automatically handles FormData parsing, type coercion, and provides a clean submission interface.
Live Examples
React - Form actions with useActionState: StackBlitz | Source
SvelteKit - Server-side form actions: StackBlitz | Source
API Reference
Functions
parseFormData- Parse FormData with schema validation and get Submission objectdecode- Convert FormData to structured objects (no validation)serialize- Transform typed values back to form-compatible stringsgetPath- Safely access nested values using dot/bracket notationsetPath- Immutably set nested values using dot/bracket notationcoerceX- A set of coercion functions for use with schema libraries
Types
Submission- Standardized submission result with success/error statesPathsFromObject- Type utility to extract all possible object paths
Valibot Utilities
⚠️ Experimental: These utilities are still in development and may change.
- Coercion Pipes - Pipes for automatic form input preprocessing
License
Conformal is licensed under the MIT License.