Add better control over submission serialization (#10342)

.changeset/raw-payload-submission-router.md

@@ -0,0 +1,20 @@
+---
+"@remix-run/router": minor
+---
+
+Add support for a new `payload` parameter for `router.navigate`/`router.fetch` submissions. This allows you to submit data to an `action` without requiring serialization into a `FormData` instance. This `payload` value will be passed unaltered to your `action` function.
+
+```js
+router.navigate("/", { payload: { key: "value" } });
+
+function action({ request, payload }) {
+  // payload      => { key: 'value' }
+  // request.body => null
+}
+```
+
+You may also opt-into serialization of this `payload` into your `request` using the `formEncType` parameter:
+
+- `formEncType: "application/x-ww-form-urlencoded"` => serializes into `request.formData()`
+- `formEncType: "application/json"` => serializes into `request.json()`
+- `formEncType: "text/plain"` => serializes into `request.text()`

.changeset/raw-payload-submission.md

@@ -0,0 +1,105 @@
+---
+"react-router-dom": minor
+---
+
+- Support better submission and control of serialization of raw payloads through `useSubmit`/`fetcher.submit`. The default `encType` will still be `application/x-www-form-urlencoded` as it is today, but actions will now also receive a raw `payload` parameter when you submit a raw value (not an HTML element, `FormData`, or `URLSearchParams`).
+
+The default behavior will still serialize into `FormData`:
+
+```jsx
+function Component() {
+  let submit = useSubmit();
+  submit({ key: "value" });
+  // navigation.formEncType => "application/x-www-form-urlencoded"
+  // navigation.formData    => FormData instance
+  // navigation.payload     => { key: "Value" }
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => "application/x-www-form-urlencoded"
+  // request.formData                    => FormData instance
+  // payload                             => { key: 'value' }
+}
+```
+
+You may opt out of this default serialization using `encType: null`:
+
+```jsx
+function Component() {
+  let submit = useSubmit();
+  submit({ key: "value" }, { encType: null });
+  // navigation.formEncType => null
+  // navigation.formData    => undefined
+  // navigation.payload     => { key: "Value" }
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => null
+  // request.formData                    => undefined
+  // payload                             => { key: 'value' }
+}
+```
+
+_Note: we plan to change the default behavior of `{ encType: undefined }` to match this "no serialization" behavior in React Router v7. In order to better prepare for this change, we encourage developers to add explicit content types to scenarios in which they are submitting raw JSON objects:_
+
+```jsx
+function Component() {
+  let submit = useSubmit();
+
+  // Change this:
+  submit({ key: "value" });
+
+  // To this:
+  submit({ key: "value" }, { encType: "application/x-www-form-urlencoded" });
+}
+```
+
+- You may now also opt-into different types of serialization of this `payload` into your `request` using the `formEncType` parameter:
+
+```js
+function Component() {
+  let submit = useSubmit();
+  submit({ key: "value" }, { encType: "application/json" });
+  // navigation.formEncType => "application/json"
+  // navigation.formData    => undefined
+  // navigation.payload     => { key: "Value" }
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => "application/json"
+  // request.json                        => { key: 'value' }
+  // payload                             => { key: 'value' }
+}
+```
+
+```js
+function Component() {
+  let submit = useSubmit();
+  submit({ key: "value" }, { encType: "application/x-www-form-urlencoded" });
+  // navigation.formEncType => "application/x-www-form-urlencoded"
+  // navigation.formData    => FormData instance
+  // navigation.payload     => { key: "Value" }
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => "application/x-www-form-urlencoded"
+  // request.formData                    => { key: 'value' }
+  // payload                             => { key: 'value' }
+}
+```
+
+```js
+function Component() {
+  let submit = useSubmit();
+  submit("Plain ol' text", { encType: "text/plain" });
+  // navigation.formEncType => "text/plain"
+  // navigation.formData    => undefined
+  // navigation.payload     => "Plain ol' text"
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => "text/plain"
+  // request.text                        => "Plain ol' text"
+  // payload                             => "Plain ol' text"
+}
+```

docs/hooks/use-fetcher.md

@@ -38,6 +38,7 @@ function SomeComponent() {
   // build your UI with these properties
   fetcher.state;
   fetcher.formData;
+  fetcher.payload;
   fetcher.formMethod;
   fetcher.formAction;
   fetcher.data;
@@ -132,6 +133,8 @@ export function useIdleLogout() {
 }
 ```
 
+`fetcher.submit` is a wrapper around a [`useSubmit`][use-submit] call for the fetcher instance, so it also accepts the same options as `useSubmit`.
+
 If you want to submit to an index route, use the [`?index` param][indexsearchparam].
 
 If you find yourself calling this function inside of click handlers, you can probably simplify your code by using `<fetcher.Form>` instead.
@@ -200,6 +203,8 @@ function TaskCheckbox({ task }) {
 }
 ```
 
+If you opt-out of serialization using `encType: null`, then `fetcher.formData` will be `undefined` and your data will be exposed on `fetcher.payload`.
+
 ## `fetcher.formAction`
 
 Tells you the action url the form is being submitted to.
@@ -224,10 +229,15 @@ fetcher.formMethod; // "post"
 
 <docs-warning>The `fetcher.formMethod` field is lowercase without the `future.v7_normalizeFormMethod` [Future Flag][api-development-strategy]. This is being normalized to uppercase to align with the `fetch()` behavior in v7, so please upgrade your React Router v6 applications to adopt the uppercase HTTP methods.</docs-warning>
 
+## `fetcher.payload`
+
+Any POST, PUT, PATCH, or DELETE that started from a `fetcher.submit(payload, { encType: null })` will have your `payload` value represented in `fetcher.payload`.
+
 [loader]: ../route/loader
 [action]: ../route/action
 [pickingarouter]: ../routers/picking-a-router
 [indexsearchparam]: ../guides/index-search-param
 [link]: ../components/link
 [form]: ../components/form
 [api-development-strategy]: ../guides/api-development-strategy
+[use-submit]: ./use-submit.md

docs/hooks/use-navigation.md

@@ -23,6 +23,7 @@ function SomeComponent() {
   navigation.state;
   navigation.location;
   navigation.formData;
+  navigation.payload;
   navigation.formAction;
   navigation.formMethod;
 }
@@ -90,8 +91,14 @@ let isRedirecting =
 
 Any POST, PUT, PATCH, or DELETE navigation that started from a `<Form>` or `useSubmit` will have your form's submission data attached to it. This is primarily useful to build "Optimistic UI" with the `submission.formData` [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object.
 
+If you opt-out of serialization using `encType: null`, then `navigation.formData` will be `undefined` and your data will be exposed on `navigation.payload`.
+
 In the case of a GET form submission, `formData` will be empty and the data will be reflected in `navigation.location.search`.
 
+## `navigation.payload`
+
+Any POST, PUT, PATCH, or DELETE navigation that started from a `useSubmit(payload, { encType: null })` will have your `payload` value represented in `navigation.payload`.
+
 ## `navigation.location`
 
 This tells you what the next [location][location] is going to be.

docs/hooks/use-submit.md

@@ -78,6 +78,48 @@ formData.append("cheese", "gouda");
 submit(formData);
 ```
 
+### Payload Serialization
+
+You may also submit raw JSON to your `action` and the default behavior will be to encode the key/values into `FormData`:
+
+```tsx
+let obj = { key: "value" };
+submit(obj); // -> request.formData()
+```
+
+You may also choose which type of serialization you'd like via the `encType` option:
+
+```tsx
+let obj = { key: "value" };
+submit(obj, { encType: 'application/x-www-form-urlencoded' }); // -> request.formData()
+```
+
+```tsx
+let obj = { key: "value" };
+submit(obj, { encType: "application/json" }); // -> request.json()
+```
+
+```tsx
+let text = "Plain ol' text";
+submit(obj, { encType: "text/plain" }); // -> request.text()
+```
+
+<docs-warn>In future versions of React Router, the default behavior will not serialize raw JSON payloads. If you are submitting raw JSON today it's recommended to specify an explicit `encType`.</docs-warn>
+
+### Opting out of serialization
+
+Sometimes in a client-side application, it's overkill to require serialization into `request.formData` when you have a raw JSON object in your component and want to submit it to your `action` directly. If you'd like to opt out of serialization, you can pass `encType: null` to your second options argument, and your data will be sent to your action function verbatim as a `payload` parameter:
+
+```tsx
+let obj = { key: "value" };
+submit(obj, { encType: null });
+
+function action({ request, payload }) {
+  // payload is `obj` from your component
+  // request.body === null
+}
+```
+
 ## Submit options
 
 The second argument is a set of options that map directly to form submission attributes:

docs/route/action.md

@@ -101,6 +101,22 @@ formData.get("lyrics");
 
 For more information on `formData` see [Working with FormData][workingwithformdata].
 
+### Opt-in serialization types
+
+Note that when using [`useSubmit`][usesubmit] you may also pass `encType: "application/json"` or `encType: "text/plain"` to instead serialize your payload into `request.json()` or `request.text()`.
+
+## `payload`
+
+A `payload` is provided to your action when you submit imperatively with [`useSubmit`][usesubmit] and provide a raw javascript value. This value might also be serialized into the request depending on the `encType`.
+
+```jsx
+function Component {
+  let submit = useSubmit();
+  submit({ key: "value" }, { encType: null });
+  // action payload is { key: 'value' }
+}
+```
+
 ## Returning Responses
 
 While you can return anything you want from an action and get access to it from [`useActionData`][useactiondata], you can also return a web [Response][response].
@@ -144,5 +160,6 @@ For more details and expanded use cases, read the [errorElement][errorelement] d
 [form]: ../components/form
 [workingwithformdata]: ../guides/form-data
 [useactiondata]: ../hooks/use-action-data
+[usesubmit]: ../hooks/use-submit
 [returningresponses]: ./loader#returning-responses
 [createbrowserrouter]: ../routers/create-browser-router

docs/route/should-revalidate.md

@@ -66,6 +66,7 @@ interface ShouldRevalidateFunction {
     formAction?: Submission["formAction"];
     formEncType?: Submission["formEncType"];
     formData?: Submission["formData"];
+    payload?: Submission["payload"];
     actionResult?: DataResult;
     defaultShouldRevalidate: boolean;
   }): boolean;

package.json

@@ -114,10 +114,10 @@
       "none": "15.6 kB"
     },
     "packages/react-router-dom/dist/react-router-dom.production.min.js": {
-      "none": "11.8 kB"
+      "none": "12 kB"
     },
     "packages/react-router-dom/dist/umd/react-router-dom.production.min.js": {
-      "none": "17.7 kB"
+      "none": "17.9 kB"
     }
   }
 }