Order of Server Action arguments when used with/without useFormState

[robertwbradford]

Summary

I'm curious about the order of arguments in a Server Action function. The formData argument "moves" when the function is then used with useFormState.

For example, currently in https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#server-only-forms it shows a basic example like this:

export default function Page() {
  async function create(formData) {
    'use server'
 
    // mutate data
    // revalidate cache
  }
 
  return <form action={create}>...</form>
}

However, later in the page at https://nextjs.org/docs/app/building-your-application/data-fetching/forms-and-mutations#error-handling it shows an Error Handling example with the following where formData needs to move to the second argument:

// app/action.js

'use server'
 
export async function createTodo(prevState, formData) {
  try {
    await createItem(formData.get('todo'))
    return revalidatePath('/')
  } catch (e) {
    return { message: 'Failed to create' }
  }
}

// app/add-form.jsx

'use client'
 
import { experimental_useFormState as useFormState } from 'react-dom'
import { experimental_useFormStatus as useFormStatus } from 'react-dom'
import { createTodo } from '@/app/actions'
 
const initialState = {
  message: null,
}
 
function SubmitButton() {
  const { pending } = useFormStatus()
 
  return (
    <button type="submit" aria-disabled={pending}>
      Add
    </button>
  )
}
 
export function AddForm() {
  const [state, formAction] = useFormState(createTodo, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="todo">Enter Task</label>
      <input type="text" id="todo" name="todo" required />
      <SubmitButton />
      <p aria-live="polite" className="sr-only">
        {state?.message}
      </p>
    </form>
  )
}

This means when we going to use our Server Action along with useFormState, we need to change its signature. This threw me off the first time trying to use useFormState.

From a reusability perspective, when someone creates a Server Action function, they don't necessarily know where it is going to be consumed. If one form decides to use useFormState while another does not, we run into problems.

I don't see any discussion in the React PRs about the order of arguments. I get that useFormState is creating a different function as the second item in its returned array, but I'm wondering if it would be more ergonomic to swap prevState and formData. Would consumers be using formData more than prevState?

Anyway, since this is a react-dom feature, the discussion may belong elsewhere, but I wasn't sure where to bring this up.

Additional information

No response

Example

No response