Writing a custom transport

type UploadTransport = {
	upload(
		file: MediaDropFile,
		context: {
			onProgress: (progress: { loaded: number; total: number | null }) => void;
			signal: AbortSignal;
		},
	): Promise<{ response?: unknown }>;
};

​

What must a transport do?

• One file, one attempt. Send the file, report progress, resolve or reject. The queue decides whether to retry — you don’t.
• Call onProgress as the upload progresses. Use total: null when the length can’t be determined.
• Wire signal’s abort event to whatever cancellation your transport has (e.g. XMLHttpRequest.abort(), fetch’s own signal support).
• Resolve with { response } — anything, opaque to the engine (e.g. the server’s parsed JSON body) — on success. Reject on failure.
• Do not implement your own retry or backoff inside the transport. Use the shared withRetry engine (re-exported from react-mediadrop) for any finer-grained retry the transport itself needs — see Upload. This is a direct reaction to a real anti-pattern: libraries that let every transport carry its own independent copy of retry/backoff logic end up with subtly different retry behavior per transport, and no single place to fix a bug in it. react-mediadrop has one retry engine, and this is where you plug into it.
• Do not implement your own concurrency limit. The queue decides how many uploads run at once; your transport just services one call at a time when asked.

​

What does a minimal transport look like?

import { withRetry, type UploadTransport } from "react-mediadrop";

function createMyTransport(options: { endpoint: string }): UploadTransport {
	return {
		async upload(file, { onProgress, signal }) {
			const response = await fetch(options.endpoint, {
				method: "POST",
				body: file.file,
				signal,
			});

			if (!response.ok) {
				throw new Error(`Upload failed: ${response.status}`);
			}

			onProgress({ loaded: file.size, total: file.size });
			return { response: await response.json() };
		},
	};
}

​

What about multi-request transports?