Form Actions: sostituire le API Routes per le mutazioni

Nelle applicazioni Next.js tradizionali, l'invio dei moduli richiede un componente client con un gestore onSubmit che chiama fetch() per inviare i dati tramite POST a una route API. Questo pattern funziona, ma richiede di scrivere e mantenere separatamente sia la logica fetch lato client sia il gestore della route lato server.

Con le Server Actions, si sostituiscono la chiamata fetch e la route API con un'unica funzione. All'elemento modulo viene assegnata la Server Action come prop action: <form action={serverAction}>. React intercetta l'invio e chiama automaticamente l'action con i dati del modulo.

Quando viene attivata da un modulo, la Server Action riceve automaticamente un oggetto FormData come argomento. È possibile accedere ai singoli campi usando formData.get('email'), che restituisce il valore come stringa. Sono disponibili tutti i metodi standard di FormData, incluso getAll() per i campi con selezione multipla.

Una Server Action può restituire un valore serializzabile che il client può utilizzare. Restituire un oggetto di errore come { error: 'Email already exists' } o un flag di successo come { success: true } consente al client di aggiornare l'interfaccia di conseguenza senza ricaricare completamente la pagina.

Poiché l'action del modulo è una Server Action, il componente della pagina che ospita il modulo non deve essere un Client Component. Il server esegue il rendering del modulo come HTML statico e solo le parti interattive, come la visualizzazione degli errori, richiedono JavaScript lato client. Questo riduce notevolmente le dimensioni del bundle client.

Un modulo con action={serverAction} funziona anche senza JavaScript abilitato. Il browser esegue un normale POST di un modulo HTML, il server esegue l'action e restituisce la pagina aggiornata. Questo vero progressive enhancement consente al modulo di funzionare correttamente in qualsiasi ambiente.

Dopo che una Server Action ha modificato i dati, i dati memorizzati nella cache della pagina devono essere aggiornati. La chiamata a revalidatePath('/dashboard') all'interno dell'action invalida la cache di Next.js per quel percorso, facendo sì che la richiesta successiva recuperi dati aggiornati. Questo è il modo standard per mantenere aggiornate le pagine renderizzate dal server dopo le mutazioni.

revalidateTag('user-data') offre un'invalidazione della cache più precisa rispetto a revalidatePath. Si aggiungono tag alle chiamate fetch con next: { tags: ['user-data'] } e poi si invalidano contemporaneamente tutti i dati contrassegnati dall'interno della Server Action, indipendentemente dai percorsi in cui tali dati vengono visualizzati.

Le Server Actions possono reindirizzare l'utente a una nuova pagina dopo una mutazione completata correttamente, chiamando redirect('/success') dal modulo next/navigation. Il reindirizzamento viene gestito lato server, quindi il browser riceve una risposta di navigazione corretta anziché un reindirizzamento lato client.

Le Server Actions non sono limitate all'invio dei moduli. Per i clic sui pulsanti e altri eventi non associati a un modulo, è necessario racchiudere la chiamata all'action in startTransition(() => action(arg)). In questo modo la navigazione viene contrassegnata come transizione e React può mantenere visibile l'interfaccia corrente mentre l'action viene eseguita sul server.

Le Server Actions sono il posto giusto per la validazione lato server. È necessario validare i campi di FormData, restituire gli errori di validazione in caso di esito negativo e procedere con la mutazione solo se tutti i campi sono validi. Librerie come Zod si integrano bene in questo contesto: è possibile analizzare FormData in base a uno schema tipizzato e restituire la mappa degli errori in caso di fallimento.

Quale argomento riceve una Server Action quando viene attivata dall'invio di un modulo?

Le Server Actions sostituiscono il pattern fetch + route API per le mutazioni dei moduli. La prop action del modulo accetta direttamente una Server Action, che riceve un oggetto FormData. Le action restituiscono risultati serializzabili per aggiornare l'interfaccia del client, supportano revalidatePath e revalidateTag per l'invalidazione della cache e funzionano progressivamente anche senza JavaScript.