Better actions with opt-in serialization of payload data

[ryanflorence]

Better Actions

Because React Router doesn't actually go to the network, there's no reason to serialize the form values, force FormData, or require a route with a path in order to take advantage of the rest of the mutation flow (with pending states, optimistic UI, revalidation, and error/race conditions handling).

This enforcement of FormData (de)serialization makes adoption of the router's mutation workflows difficult, and the only justification for the friction is "it'll make migrating to Remix easier". While we'd love for many React Router apps to get the benefits of migrating to Remix, the APIs in Router shouldn't artificially enforce the same constraints as a full-stack application.

Proposal

• Have encType: null indicate you don't want to serialize it into to the request body sent to the action
  • In v6 we will use null to avoid a breaking change to the current behavior of encType: undefined which serializes by default
  • in v7 we will change the default behavior of encType: undefined to not serialize and you can opt into serialization via encType: "application/x-www-form-urlencoded"
• Allow functions as the action to submit() and fetcher.submit() instead of just route paths
  • when an action function is provided it'll behave as a navigation to the current route and the provided function will act as an action function override (so if the route doesn't have an action, it won't 405, and if the route does have an action it won't be called).
• Pass the payload, unchanged, to the action instead of serializing into the request

function Comp() {
  let submit = useSubmit();

  useEffect(() => {
    submit(
      { foo: "bar" },
      {
        // action can be an arbitrary action function, no need for a route
        action: someAction,
        encType: null, // don't serialize this payload
      }
    );
  }, []);

  // ...
}

Because React Router doesn't actually go to the network, there's no reason to serialize the values to go over the network, they'll come straight to the action on the second argument:

function someAction({ params, request }, payload) {
  console.log(payload); // { foo: { bar: 1, baz: 2 } }
}

It's also visible to the type system, so you can have type safety:

type TodoSubmission = {
  name: string;
  projectId: number;
};

async function createTodo(_: ActionArgs, payload: TodoSubmission) {
  await createTodo(payload);
}

submit(
  // this is typesafe
  {
    name: "make router better for SPAs",
    projectId: 23,
  },
  { action: createTodo }
);

The payload will be available to other places as well:

let navigation = useNavigation();
navigation.payload; // { name, projectId }

function shouldRevalidate({ payload }) {}

In other words, wherever formData shows up, payload will be there too. They are mutually exclusive, you won't ever have both.

Fetchers

Same story for fetchers:

let fetcher = useFetcher();
fetcher.submit({ name, projectId }, { action: someAction, encType: null });
fetcher.payload;

Opt-in to serialization

If an enctype is defined, the value will be encoded into the request body that goes to the action:

submit(new FormData(), {
  action: someAction,
  encType: "application/x-www-form-urlencoded",
});

submit(
  { foo: "bar" },
  { action: someAction, encType: "application/json" }
);

Now the value will be serialized into the request body:

function someAction({ request }, payload) {
  let type = request.headers.get("Content-Type");

  // the payload is serialized into the request body now
  switch (type) {
    case "application/json": {
      let json = await request.json();
      console.log(payload); // undefined
    }

    case "application/x-www-form-urlencoded": {
      let formData = await request.formData();
      console.log(payload); // undefined
    }

    case "text/plain": {
      let text = await request.text();
      console.log(payload); // undefined
    }

    case null: {
      console.log(payload); // the value they submitted
    }
  }
}

This allows code to be shared between React Router, Remix, and anything else that operates on the Web Fetch API, but no longer forces it.

Remix

This sets the foundation to allow application/json for submit and fetcher.submit in Remix apps. While that will break "progressive enhancement by default", it's opt-in, and many applications could benefit greatly from using request.json() instead of messing with formData (in my experience, particularly graphqlAPIs where the data you get and post are deeply nested)

[brophdawg11]

This proposal supersedes #9858

[brophdawg11]

Implemented in #10342 and #10362.

Type inference still to come in a new PR

[brophdawg11]

Note we are backing these PRs out from the 6.11 release since we're iterating on the API a bit more (see below), so they will likely be available in 6.12.

[HIMISOCOOL]

Hey there @brophdawg11 , are these changes still on board?

[brophdawg11]

Yes - #10324 (comment)

[mjackson]

Thanks @ryanflorence and @brophdawg11 for chatting with me earlier today to help me understand what's going on here. I think I agree with about 90% of what's going on here. There's just one part that bothers me, and it's the payload arg being added to loader/action and navigation objects. Also, encType: null feels a little strange and non-standard to me.

I'd like to propose the following modifications:

• encType is never null. It defaults to application/x-www-form-urlencoded (as it does today) and otherwise must be a valid mime type
• Instead of adding a payload arg everywhere, we can introduce navigation.json and navigation.text properties for application/json and text/plain request payloads. Like navigation.formData, this mirrors request.json() and request.text() except, instead of being async these properties are available immediately. (Eventually we may want to introduce navigation.arrayBuffer for folks who are working with binary data in the browser, but that's outside of scope for this proposal).

I feel like these tiny changes stay closer with our current abstraction (the fetch API) and help us avoid API sprawl.

Example: submitting JSON object to an action

function Comp() {
  let submit = useSubmit();
  let navigation = useNavigation();

  // navigation.json is *the same object* that was given in submit(obj). No need
  // to serialize in a purely client-side app.
  console.log(navigation.json);

  useEffect(() => {
    submit(
      { foo: "bar" },
      {
        // action can be an arbitrary action function, no need for a route
        action: someAction,
        // treat the payload as JSON (this does not imply that we must *serialize*
        // the payload. it just indicates the user's intent: "treat this as JSON")
        encType: "application/json",
      }
    );
  }, []);

  // ...
}

Example: submitting JSON string to an action

This is similar to Ryan's "opting into serialization" section above. The user may opt in to serialization by JSON.stringifying the payload themselves, and we can simply JSON.parse that string and give it to the user on navigation.json:

function Comp() {
  let submit = useSubmit();
  let navigation = useNavigation();

  // navigation.json is a JSON.parse'd version of the thing they gave us in submit(str)
  console.log(navigation.json);

  useEffect(() => {
    submit(
      // Opt-in to serialization by doing it yourself in the case of application/json
      JSON.stringify({ foo: "bar" }),
      {
        // action can be an arbitrary action function, no need for a route
        action: someAction,
        // treat the payload as JSON (this does not imply that we must *serialize*
        // the payload. it just gives us its type)
        encType: "application/json",
      }
    );
  }, []);

  // ...
}

The internal heuristics of the router would basically be: if the encType is application/json and the user gave us a string payload, try to JSON.parse it before returning it in navigation.json.

Example: fetcher

The fetcher use case is similarly simple to Ryan's except you need to use an encType that lets us know your intent.

let fetcher = useFetcher();
fetcher.submit({ name, projectId }, { action: someAction, encType: "application/json" });
fetcher.json;

Example: an action

async function someAction({ request } /* no additional payload arg needed here */) {
  let type = request.headers.get("Content-Type");

  // the payload is serialized into the request body now
  switch (type) {
    case "application/json": {
      // this may return either the JSON.parse'd version of a serialized body or the
      // raw value that was passed to submit(obj)
      let json = await request.json();
    }

    case "application/x-www-form-urlencoded": {
      let formData = await request.formData();
    }

    case "text/plain": {
      let text = await request.text();
    }

    // invalid! Content-Type must always be defined
    //case null: {}
  }
}

Implementation notes

• In the case of submit(obj) we should preserve the identity of the object in navigation.json and request.json() in the loader/action. This is key because it allows people to bypass serialization and preserve object identity
• Accessing the wrong property on navigation for the given encType should probably throw. For example, accessing navigation.json on an application/x-www-form-urlencoded request should throw, the same as request.json() would reject in that case
• We might wanna always allow accessing navigation.text as a special case. I don't believe request.text() ever rejects. It just gives you the stringify'd contents of the request body. This would need to be done according to the encType of the payload, so e.g. we would return JSON.stringify(obj) in navigation.text when using application/json with submit(obj).

[brophdawg11]

Going to dig into this this AM. We should be able to preserve object identity in navigation.json, but not in request.json since it has to be serialized in order to create the request:

new Request("/", { 
  method: "post", 
  headers: { "Content-type": 'application/json' }, 
  body: JSON.stringify({ a: 'b' }),
})

However, it occurs to me that the introduction of direct/inline actions actually solves this for us in that use-case since your inline action has direct access to the object, so you don't need a payload or request.json:

  let fetcher = useFetcher();
  let [myObject, setMyObject] = React.useState({});
  let handleSubmit = React.useCallback(() => {
    fetcher.submit(myObject, {
      method: "post",
      encType: "application/json",
      async action({ request }) {
        // You can deserialize a *new* object identity in the action
        let deserialized = await request.json();
        // But with inline actions you have direct access to the source object
        console.log("myObject", myObject);
        // They are not the same:
        console.log(deserialized === myObject); // false
      },
    });
  }, [fetcher, myObject]);

So maybe that's the concession? When submitting to a route action, you lose identity and can deserialize via request.json(). If you require object identity, then you can use an inline action.

[dadamssg]

i like what @brophdawg11 points out, using the payload directly. Using request.json() struck me as awkward. If i'm using just react-router, i'd like to avoid using faux routes and request objects.

[mjackson]

Yep, that sounds good. Using inline loader/action allows you to avoid serializing the payload completely since you're in the same scope. I like this too 👍

[ryanflorence]

Love it. After talking to Michael I think this is what I'd like to do:

• add application/json, text/plain encType support for
  • <Form>
  • useSubmit
  • <fetcher.Form>
  • fetcher.submit
• pending states for new encTypes next to formData
  • navigation.json, navigation.text
  • fetcher.json, fetcher.text
• inline loaders and actions for:
  • fetcher.load(inlineLoader)
  • fetcher.submit(o, { action: inlineAction })

But we won't be adding inline actions to useSubmit. useSubmit is a mutation to both your data and the history stack (a navigation). If the action is a function, and not a URL, there is nowhere to navigate, so the semantics don't line up. Fetchers already don't cause navigations so the semantics line up just fine.

We will serialize, even in the application/json case because as Matt pointed out, whatever object the developer is submitting, they have access to that object when they submit, so they can get it where it needs to go. If they want access to the values being submitted from some other part of the UI (like the root), they will use the serialized version of it from navigation.json|text|formData and useFetchers()[index].json|text|formData.

[brophdawg11]

Note discussed offline and we are not adding the additional encType's to Form/fetcher.Form to keep with browser <form> semantics

[mjackson]

OK so if I had to summarize what this proposal is adding I'd say two things:

• inline (no associated URL/route) loader and action for fetchers
• addition of navigation.json and navigation.text for improved handling of JSON/alternative (non-HTML form) content types

[brophdawg11]

#10413 is merged to dev and should be available once 6.13.0 is released.

A few notes on the final landing spot for the implementation:

• Inline loaders/actions are not currently included. We need to think about this more and see how it works if you bring react server/client actions into the picture
• json/text submissions will be reflected in the json/text fields of navigations and fetchers
• json/text/formData fields on navigations and fetchers are mutually exclusive and only one will be filled at a time. The others will be undefined.
• <Form encType="text/plain"> is supported since it's in the spec but <Form> does not support application/json

[brophdawg11]

This will be 6.14.0 now - 6.13.0 was used to add a feature flag for React.startTransition

[patrikholcak]

Has it been pushed to 6.14 due to how 6.13 turned out?

[brophdawg11]

Yes, should be in 6.14, likely next week

[siukalov]

great job on this, when do you think we can get inline loaders/actions?