Typed Action Dispatch — a pattern for end-to-end type-safe mutations

[zabi-babar]

Typed Action Dispatch — a pattern for end-to-end type-safe mutations

---

Summary

React Router 7 has made great strides in type safety for loaders and route data, but mutations still rely on untyped FormData as the serialization boundary between components and route actions. This means the response side of a mutation can be typed, but the request side cannot — leaving half the contract enforced by convention rather than the type system.

This post outlines three specific issues with the current approach and proposes a pattern to address them, along with a working reference implementation.

---

Issue 1: useFetcher is half-typed

With React Router 7's type inference, useFetcher<typeof action>() gives you typed return data. But the submission side is completely untyped:

const fetcher = useFetcher<typeof action>();

// ✅ Typed — `fetcher.data` knows the action's return type
if (fetcher.data?.success) { ... }

// ❌ Untyped — no guarantee this matches what the action expects
const formData = new FormData();
formData.append("name", name);
formData.append("email", email);
// Did I forget a field? Is "email" the right key? Is it a string?
fetcher.submit(formData, { method: "POST" });

The type system protects the response but is silent about the request. If the action changes its expected fields, the component compiles fine and breaks at runtime.

---

Issue 2: FormData is a lossy serialization boundary

formData.get() returns FormDataEntryValue | null (string | File | null). Everything goes in as a string and comes out as a string. This means:

• Numbers need Number(formData.get("priority")) — and you hope it's not NaN
• Booleans become formData.get("active") === "true" — a string comparison
• Arrays require formData.getAll() — and the action has to know which fields are arrays
• Dates, Sets, Maps — no standard encoding at all
• Nested objects — you're on your own (JSON.stringify into a single field, or flatten with dot notation)

Every action re-invents this parsing. Across 10, 20+ mutations in an app, this becomes a significant source of bugs and boilerplate.

---

Issue 3: The switch(intent) pattern — a case for the strategy pattern

When a route handles multiple mutations, the common approach is to branch on an intent field:

export async function action({ request }: Route.ActionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent");

  switch (intent) {
    case "updateProfile": {
      const name = String(formData.get("name"));
      const email = String(formData.get("email"));
      const bio = String(formData.get("bio"));
      return await updateProfile({ name, email, bio });
    }
    case "changePassword": {
      const currentPassword = String(formData.get("currentPassword"));
      const newPassword = String(formData.get("newPassword"));
      return await changePassword({ currentPassword, newPassword });
    }
    case "deleteAccount": {
      const confirmation = String(formData.get("confirmation"));
      return await deleteAccount({ confirmation });
    }
    default:
      throw new Response("Unknown intent", { status: 400 });
  }
}

This works, but it's essentially a manual dispatch table — each branch parses different fields from the same untyped FormData, with no shared structure and no compile-time verification that the component is sending the right fields for the right intent.

This is a textbook case for the strategy pattern: define each mutation as a self-contained unit with its own typed payload and resolver, then let a single dispatch mechanism route to the correct one.

---

The pattern: defineAction + resolveFormData + useActionFetcher

The idea is three primitives:

1. Define each mutation as a typed action

import { defineAction } from "react-router-typed-actions";

export const updateProfile = defineAction({
  type: "settings/updateProfile",
  resolve: (payload: { name: string; email: string; bio: string }) =>
    api.settings.updateProfile(payload),
});

export const changePassword = defineAction({
  type: "settings/changePassword",
  resolve: (payload: { currentPassword: string; newPassword: string }) =>
    api.settings.changePassword(payload),
});

export const deleteAccount = defineAction({
  type: "settings/deleteAccount",
  method: "DELETE",
  resolve: (payload: { confirmation: string }) =>
    api.settings.deleteAccount(payload),
});

Each action carries its payload type, return type, and resolver in one place.

2. Replace the switch with a single dispatch

import { resolveFormData, actionSuccess, actionFailure } from "react-router-typed-actions";

// can be extracted since most routes will have the same clientAction fn now
export async function clientAction({ request }: Route.ClientActionArgs) {
  const formData = await request.formData();
  const action = resolveFormData(formData);

  try {
    const response = await action.resolve();
    return actionSuccess(action, response);
  } catch (error) {
    return actionFailure(action, error);
  }
}

No switch. No manual parsing. The action type in the FormData maps to the registered definition, the payload is deserialized with full type fidelity (including Dates, Maps, Sets, Files), and the resolver runs.

3. Use a typed hook on the component side

import { useActionFetcher } from "react-router-typed-actions";
import { updateProfile } from "~/domain/settings/actions";

function ProfileForm() {
  const [submit, { state, data }] = useActionFetcher(updateProfile, {
    onSuccess: () => toast.success("Profile updated"),
    onError: (err) => toast.error(String(err)),
  });

  return (
    <button
      onClick={() => submit({ name, email, bio })}
      //                    ^ type-checked: { name: string; email: string; bio: string }
      disabled={state !== "idle"}
    >
      Save
    </button>
  );
}

submit() is fully typed to the action's payload. If you pass the wrong shape, the compiler catches it. The response in data is typed to the action's return type. No FormData construction, no useEffect for callbacks.

---

What this gives you

• End-to-end type safety — payload types flow from defineAction through useActionFetcher to resolveFormData. Change a field name and the compiler tells you everywhere that breaks.
• No manual FormData plumbing — serialization is handled automatically via SuperJSON, preserving Dates, Maps, Sets, BigInts, and extracting Files/Blobs as native FormData entries.
• Strategy pattern dispatch — route actions become a generic one-liner. Add a new mutation by defining an action and registering it, not by adding another case branch.
• Built-in pending state — pendingPayload deserializes the in-flight fetcher.formData for optimistic UI without extra work.
• Lifecycle callbacks — onSuccess / onError without useEffect boilerplate.

---

Reference implementation

I've been experimenting with this pattern and captured it in a working implementation: react-router-typed-actions. It's ~3 KB, has no dependencies beyond SuperJSON, and works with both client and server actions.

I'd love feedback on:

• Whether the defineAction / resolveFormData split feels natural
• The global registry approach (actions are registered at startup and looked up by type string)
• Whether this pattern is something worth standardizing, or if there are better primitives React Router could expose to enable it