Docs: Note $ACTION_ formData properties

[karlhorky]

What?

Make a note about the new $ACTION_ properties in the formData

Why?

Since next@14.1.3, some new $ACTION_ properties have appeared in the formData in development mode, which cause validation errors when used with a strict validation with a library such as Zod or Yup:

// Form Client Component
export default function Form() {
  const [state, formAction] = useFormState(action, {
    type: 'initial',
  });

  return (
    <form action={action}>
      {/* ... */}
    </form>
  );
}

// Server Action
export async function action(
  prevState: ServerActionReturnValue,
  formData: FormData,
): Promise<ServerActionReturnValue> {
  const validationResult = await schema.validate(
    Object.fromEntries(formData.entries()),
  );

The errors from Yup:

Errors:

- this field has unspecified keys: $ACTION_REF_1, $ACTION_1:0, $ACTION_1:1, $ACTION_KEY

The data in the formData.entries()

{
  '$ACTION_REF_1': '',
  '$ACTION_1:0': '{"id":"59f475b...","bound":"$@1"}',
  '$ACTION_1:1': '[{"type":"initial"}]',
  '$ACTION_KEY': 'k187677481',
  // Real form data starts here:
  year: '2024',

How?

Document additional properties with keys starting with the prefix $ACTION_

Alternatives Considered

Maybe these $ACTION_ properties are not intended to be exposed to users, and should be stripped before the formData reaches the Server Action.

Related

The documentation was originally introduced in commit 687239c, which was a part of this PR:

• Docs: Update Server Actions Docs #59080

cc @delbaoliveira

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: 5fd7a5f

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[karlhorky]

Workaround

In future, these properties with the $ACTION_ prefix may be excluded from the formData which is available in the Server Action.

In the meantime, instead of Object.fromEntries(formData.entries()), filter out the formData properties that start with $ACTION_:

// TODO: Revert to `Object.fromEntries(formData.entries())` if `$ACTION_`
// properties are omitted from Next.js dev mode Server Actions formData in future
// https://github.com/vercel/next.js/pull/63048#issuecomment-1986138940
Object.fromEntries(
  [...formData.entries()].filter(([key]) => !key.startsWith('$ACTION_')),
)

[samcx]

@karlhorky Taking a look!

[samcx]

Thank you for submitting a !

[karlhorky]

Thanks for the review and merge @samcx 🙌