Integrate with Remix multipart form parser

[aaronadamsCA]

I'm looking at how to seamlessly integrate Conform + Zod with the Remix streaming multipart/form-data parser.

https://reactrouter.com/how-to/file-uploads
https://www.npmjs.com/package/@remix-run/form-data-parser

I think these are probably the trickiest bits to get right:

• The upload handler runs once per streaming file upload, so file validation needs to operate on a single file field at a time. The rest of the field values aren't available here.
• I think you'd want to progressively enhance the form by submitting one file field, validating it on the server side using the same upload handler, and replacing its client-side value with the upload result.

Upload handler

Since Conform field names are opaque (right?), I think this part would work best if Conform provided a utility to query a form schema using a field name and get back the field schema.

Maybe that utility could also know how to search a union for a file type, but I assumed for now that part would be up to me.

const imageFieldSchema = z.union([
  z.file().mime(["image/webp"]).max(10_000_000),
  z.string().transform(parseJsonUploadResult),
]);

const schema = z.object({
  images: z.array(imageFieldSchema).min(1, "At least 1 file is required"),
});

async function uploadHandler(fileUpload) {
  // Conform utility to get a field schema from a form schema?
  const fieldSchema = getFieldSchema(schema, fileUpload.fieldName);

  // Unwrap the file schema from the union
  const fileSchema = maybeUnwrap(fieldSchema);

  // If this isn't a file field, drop the file from the form submission
  if (fileSchema == null) {
    return;
  }

  const uploadResult = await validateAndUploadFile(fileUpload, fileSchema);
  return JSON.stringify(uploadResult);
}

Progressive enhancement

I wasn't planning on figuring this part out yet, but I assume users will prefer background uploads with progress indicators.

I have no idea if this would be done using a Conform intent or something more custom.

[edmundhung]

Thanks for the detailed write up. Validating forms with file uploads has been on my list to explore for a while.

I don't consider field names opaque. Our APIs infer names mainly for convenience and type safety, but the patterns are documented and it's totally fine to specify names manually.

I can see the value of a getFieldSchema() API for complex forms that accept files with different types and validation requirements. For simpler forms though, I think it would be more straightforward to validate it directly with your image schema, knowing that's how it will be validated with Zod.

The implementation of getFieldSchema(schema, name) should be fairly straight forward. However, unwrapping unions doesn't feel quite right to me, as you could have unions over several file schemas, or additional logic that shouldn't be excluded. I think the implementation of validateAndUploadFile is also up to the users.

What do you think?

[aaronadamsCA]

Agreed on all points. 👍

For simpler forms though, I think it would be more straightforward to validate it directly with your image schema, knowing that's how it will be validated with Zod.

For sure! Heck, the easiest solution is to handle uploads right inside the server schema, but that's not compatible with streaming support.

In our case, different file fields have different constraints, which is why fetching a field schema from a form schema feels like the best DRY solution for now.

The implementation of getFieldSchema(schema, name) should be fairly straight forward. However, unwrapping unions doesn't feel quite right to me, as you could have unions over several file schemas, or additional logic that shouldn't be excluded. I think the implementation of validateAndUploadFile is also up to the users.

Agreed, sorry this wasn't clear! I'm just looking for some way to query a schema using a field name. The rest was just pseudocode.

[edmundhung]

Having said that, I just thought of a case this become tricky. For example:

const schema = z.discriminatedUnion("type", [
  z.object({ type: z.literal("profile"), file: z.file().mime(["image/webp"]) }),
  z.object({ type: z.literal("document"), file: z.file().mime(["application/pdf"]) }),
]);

const fieldSchema = getFieldSchema(schema, 'file'); // -> ???

What should getFieldSchema() return here? A union of the two file schemas? An array? Either way it feels unreliable, because you cannot really know which branch applies until you validate against the rest of the form data. That makes it hard to guarantee the uploaded file is valid at this stage.

This makes me wonder if the correct solution here is to upload it regardless as long as it passes some basic requirements (e.g. max file size), and uses the file-storage package so that you could validate the file with the rest of the form data all together:

import { LocalFileStorage } from '@remix-run/file-storage/local';
import type { FileUpload } from '@remix-run/form-data-parser';
import { parseFormData } from '@remix-run/form-data-parser';

// Set up a storage based on your requirement
const fileStorage = new LocalFileStorage('/uploads/user-avatars');

// Define how to handle incoming file uploads
async function uploadHandler(fileUpload: FileUpload) {
  // Do basic check to minimize what file we accepted
  // You can also make a union of all your file schema,
  // but the point here is to minimize unnecessary upload, not to validate the file
  if (fileUpload.fieldName === 'user-avatar') {
    let storageKey = `user-${user.id}-avatar`;

    // Put the file in storage
    await fileStorage.set(storageKey, fileUpload);

    // Return a lazy File object that can access the stored file when needed
    return fileStorage.get(storageKey);
  }

  // Ignore unrecognized fields
}

async function action() {
  let formData = await parseFormData(request, uploadHandler);
  // then validate form data all together
}

This does mean that an invalid file may get uploaded initially and wasted some resources, but in practice that is hard to avoid anyway: your action could fail after the upload for many other reasons, which means you need cleanup logic for stale files regardless. The advantage here is you keep your schema as the single source of truth for validation, and avoid guessing which branch of a union applies too early.

[aaronadamsCA]

Great points, my thoughts:

What should getFieldSchema() return here? A union of the two file schemas? An array?

I think it could just throw.

Conform already has some common-sense runtime constraints on schemas, e.g:

conform/packages/conform-zod/v4/constraint.ts

Lines 92 to 94 in 0803efd

	} else if (name === '') {
	// All the cases below are not allowed on root
	throw new Error('Unsupported schema');

Similarly, I think this utility could be restricted to traversing (non-optional?) objects and arrays.

Maybe that sounds too restrictive at first, but imagine some future version of Conform that directly parses and validates the form data stream (which would be very cool, BTW). To parse each field individually, you'd need the exact same constraints on the outer, field-defining portion of the schema.

This makes me wonder if the correct solution here is to upload it regardless as long as it passes some basic requirements (e.g. max file size)

Right, but those "basic requirements" are a form of validation, right? And at least with this utility, I could get that max file size from the field schema instead of just hard-coding it.

In our case, we also need to upload files in different fields to different destinations. Right now we do this by attaching different transforms to different field schemas; in the streaming version I was thinking we could just "tag" each field with its upload handler key using a Zod registry.

The advantage here is you keep your schema as the single source of truth for validation

Unfortunately I don't think this can ever be true with streaming uploads, because even in the simplest case (every file in every field uploaded to the same service), that service can generally return its own validation errors, too.

So no matter what we do, we probably still need to turn upload handler errors into Conform field errors, e.g. the upload handler returning JSON.stringify(errors) and the field schema parsing it back out of the form data.

[aaronadamsCA]

@edmundhung, I just made a (rather big) suggestion in #858 (comment) that would potentially make this idea a lot easier: TLDR, ship your own schema library. 😅 I know it sounds insane at first, but maybe there's something to it.