epic-forms

# Epic Stack: Forms ## When to use this skill Use this skill when you need to: - Create forms in an Epic Stack application - Implement form validation with Zod - Work with Conform for progressively enhanced forms - Handle file uploads - Implement honeypot fields for spam protection - Handle form errors - Work with complex forms (fieldsets, arrays) ## Patterns and conventions ### Validation Philosophy Following Epic Web principles: **Explicit is better than implicit** - Make validation rules clear and explicit using Zod schemas. Every validation rule should be visible in the schema, not hidden in business logic. Error messages should be specific and helpful, telling users exactly what went wrong and how to fix it. **Design to fail fast and early** - Validate input as early as possible, ideally on the client side before submission, and always on the server side. Return clear, specific error messages immediately so users can fix issues without frustration. **Example - Explicit validation:** ```typescript // ✅ Good - Explicit validation with clear error messages const SignupSchema = z.object({ email: z .string({ required_error: 'Email is required' }) .email({ message: 'Please enter a valid email address' }) .min(3, { message: 'Email must be at least 3 characters' }) .max(100, { message: 'Email must be less than 100 characters' }) .transform((val) => val.toLowerCase().trim()), password: z .string({ required_error: 'Password is required' }) .min(6, { message: 'Password must be at least 6 characters' }) .max(72, { message: 'Password must be less than 72 characters' }), }) // ❌ Avoid - Implicit validation const SignupSchema = z.object({ email: z.string().email(), // No clear error messages password: z.string().min(6), // Generic error }) ``` **Example - Fail fast validation:** ```typescript // ✅ Good - Validate early and return specific errors immediately export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() // Validate immediately - fail fast const submission = await parseWithZod(formData, { schema: SignupSchema, }) // Return errors immediately if validation fails if (submission.status !== 'success') { return data( { result: submission.reply() }, { status: 400 }, // Clear error status ) } // Only proceed if validation passed const { email, password } = submission.value // ... continue with signup } // ❌ Avoid - Delayed or unclear validation export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() const email = formData.get('email') const password = formData.get('password') // Validation scattered throughout the function if (!email) { // Generic error, not specific return json({ error: 'Invalid' }, { status: 400 }) } // ... more scattered validation } ``` ### Basic setup with Conform Epic Stack uses [Conform](https://conform.guide/) to handle forms with progressive enhancement. **Basic setup:** ```typescript import { getFormProps, useForm } from '@conform-to/react' import { getZodConstraint, parseWithZod } from '@conform-to/zod' import { z } from 'zod' import { Form } from 'react-router' const SignupSchema = z.object({ email: z.string().email(), password: z.string().min(6), }) export default function SignupRoute({ actionData }: Route.ComponentProps) { const [form, fields] = useForm({ id: 'signup-form', constraint: getZodConstraint(SignupSchema), lastResult: actionData?.result, onValidate({ formData }) { return parseWithZod(formData, { schema: SignupSchema }) }, shouldRevalidate: 'onBlur', }) return ( <Form method="POST" {...getFormProps(form)}> {/* Form fields */} </Form> ) } ``` ### Integration with Zod Conform integrates seamlessly with Zod for validation. **Define schema:** ```typescript import { z } from 'zod' const SignupSchema = z .object({ email: z.string().email('Invalid email'), password: z.string().min(6, 'Password must be at least 6 characters'), confirmPassword: z.string(), }) .superRefine(({ confirmPassword, password }, ctx) => { if (confirmPassword !== password) { ctx.addIssue({ path: ['confirmPassword'], code: 'custom', message: 'Passwords must match', }) } }) ``` **Validation in action (fail fast):** ```typescript export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() // Validate immediately - explicit and fail fast const submission = await parseWithZod(formData, { schema: SignupSchema, }) // Return explicit errors immediately if validation fails if (submission.status !== 'success') { return data( { result: submission.reply() }, { status: submission.status === 'error' ? 400 : 200 }, ) } // Only proceed if validation passed - submission.value is type-safe const { email, password } = submission.value // ... process with validated data } ``` ### Async validation For validations that require querying the database: ```typescript export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() const submission = await parseWithZod(formData, { schema: SignupSchema.superRefine(async (data, ctx) => { const existingUser = await prisma.user.findUnique({ where: { email: data.email }, select: { id: true }, }) if (existingUser) { ctx.addIssue({ path: ['email'], code: z.ZodIssueCode.custom, message: 'A user already exists with this email', }) } }), async: true, // Important: enable async validation }) if (submission.status !== 'success') { return data( { result: submission.reply() }, { status: submission.status === 'error' ? 400 : 200 }, ) } // ... } ``` ### Field Components Epic Stack provides pre-built field components: **Basic Field:** ```typescript import { Field, ErrorList } from '#app/components/forms.tsx' import { getInputProps } from '@conform-to/react' <Field labelProps={{ htmlFor: fields.email.id, children: 'Email', }} inputProps={{ ...getInputProps(fields.email, { type: 'email' }), autoFocus: true, autoComplete: 'email', }} errors={fields.email.errors} /> ``` **TextareaField:** ```typescript import { TextareaField } from '#app/components/forms.tsx' import { getTextareaProps } from '@conform-to/react' <TextareaField labelProps={{ htmlFor: fields.content.id, children: 'Content', }} textareaProps={{ ...getTextareaProps(fields.content), rows: 10, }} errors={fields.content.errors} /> ``` **CheckboxField:** ```typescript import { CheckboxField } from '#app/components/forms.tsx' import { getInputProps } from '@conform-to/react' <CheckboxField labelProps={{ htmlFor: fields.remember.id, children: 'Remember me', }} buttonProps={getInputProps(fields.remember, { type: 'checkbox' })} errors={fields.remember.errors} /> ``` **OTPField:** ```typescript import { OTPField } from '#app/components/forms.tsx' <OTPField labelProps={{ htmlFor: fields.code.id, children: 'Verification Code', }} inputProps={{ ...getInputProps(fields.code), maxLength: 6, }} errors={fields.code.errors} /> ``` ### Error Handling **Display field errors:** ```typescript <Field // ... props errors={fields.email.errors} // Errores específicos del campo /> ``` **Display form errors:** ```typescript import { ErrorList } from '#app/components/forms.tsx' <ErrorList errors={form.errors} id={form.errorId} /> ``` **Error structure:** - `fields.fieldName.errors` - Errors for a specific field - `form.errors` - General form errors (like `formErrors`) ### Honeypot Fields Epic Stack includes spam protection with honeypot fields. **In the form:** ```typescript import { HoneypotInputs } from 'remix-utils/honeypot/react' <Form method="POST" {...getFormProps(form)}> <HoneypotInputs /> {/* Always include in public forms */} {/* Rest of fields */} </Form> ``` **In the action:** ```typescript import { checkHoneypot } from '#app/utils/honeypot.server.ts' export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() await checkHoneypot(formData) // Throws error if spam // ... rest of code } ``` ### File Uploads For forms with file uploads, use `encType="multipart/form-data"`. **Schema for files:** ```typescript const MAX_UPLOAD_SIZE = 1024 * 1024 * 3 // 3MB const ImageFieldsetSchema = z.object({ id: z.string().optional(), file: z .instanceof(File) .optional() .refine((file) => { return !file || file.size <= MAX_UPLOAD_SIZE }, 'File must be less than 3MB'), altText: z.string().optional(), }) const NoteEditorSchema = z.object({ title: z.string().min(1).max(100), content: z.string().min(1).max(10000), images: z.array(ImageFieldsetSchema).max(5).optional(), }) ``` **Form with file upload:** ```typescript <Form method="POST" encType="multipart/form-data" {...getFormProps(form)} > {/* Fields */} </Form> ``` **Process files in action:** ```typescript export async function action({ request }: Route.ActionArgs) { const formData = await request.formData() const submission = await parseWithZod(formData, { schema: NoteEditorSchema, }) if (submission.status !== 'success') { return data({ result: submission.reply() }, { status: 400 }) } const { images } = submission.value // Process files for (const image of images ?? []) { if (image.file) { // Upload file, save to storage, etc. } } // ... } ``` ### Fieldsets y Arrays For forms with repetitive fields (like multiple images): **Schema:** ```typescript const ImageFieldsetSchema = z.object({ id: z.string().optional(), file: z.instanceof(File).optional(), altText: z.string().optional(), }) const FormSchema = z.object({ images: z.array(ImageFieldsetSchema).max(5).optional(), }) ``` **In the component:** ```typescript import { FormProvider, getFieldsetProps } from '@conform-to/react' const [form, fields] = useForm({ // ... defaultValue: { images: note?.images ?? [{}], }, }) const imageList = fields.images.getFieldList() return ( <FormProvider context={form.context}> <Form method="POST" {...getFormProps(form)}> {imageList.map((image, index) => { const imageFieldset = getFieldsetProps(fields.images[index]) return (