React

Server Actions vs una route API

Server Actions servono alle mutazioni chiamate da un form React; una route API serve a chi sta fuori, con un contratto stabile e testabile.

In sintesi

  • Una Server Action è una funzione eseguita sul server, chiamata da un componente: non ha un URL pubblico.
  • Una route API ha un contratto, un metodo e uno stato: serve a webhook, app mobile e terze parti.
  • Entrambe richiedono un controllo di autorizzazione esplicito: nessuna delle due lo aggiunge da sola.

Una Server Action è la scelta giusta quando la mutazione nasce da un form del tuo componente; una route API quando il chiamante è fuori dall'applicazione.

La differenza che conta

La Server Action non ha un indirizzo pubblico: Next la espone come endpoint generato e il client la chiama tramite un riferimento. Una route API ha un percorso, un metodo e un codice di stato, quindi si può documentare, versionare e chiamare con curl.

La mutazione, nella forma breve

// app/actions.ts
"use server";

export async function renameProject(id: string, name: string) {
  await db.project.update({ where: { id }, data: { name } });
  revalidatePath("/projects");
}

La direttiva "use server" marca il file; revalidatePath invalida la cache della pagina dopo la scrittura. Il componente importa la funzione e la passa a un action del form, senza fetch e senza costruire il payload.

Quando serve un URL

  • Webhook: un servizio esterno ha bisogno di un indirizzo stabile e di una firma, non di un riferimento generato.
  • Client terzi: un'app mobile o uno script non conoscono il protocollo interno di Next.
  • Osservabilità: un percorso con metodo e stato è più facile da tracciare nei log e nei test end-to-end.

Build e avvio

npx next build
npx next start

Le Server Actions richiedono un runtime Node o edge compatibile con Next: su un hosting statico non esistono, perché non c'è un server che le esegua.

Tre componenti di upload, il caso in cui la differenza si vede: use-image-upload, file-upload-card e file-upload. Per esplorare per categoria parti da 111.985 componenti.

La limitazione

Le Server Actions non sono più sicure per il fatto di essere sul server: il chiamante può invocarle con argomenti arbitrari, quindi autorizzazione e validazione vanno scritte dentro. Inoltre non sono cacheabili come una GET e non offrono un modo naturale di rispondere a un client che non è React.

Dove continuare

Il confronto diretto è in route handlers vs Server Actions; la validazione degli input è in validare le Server Actions; il confine fra i due ambienti è in server-only e client-only.

Domande frequenti

Una Server Action è più sicura di una route API?

No. Entrambe sono raggiungibili dal client, quindi autorizzazione e validazione degli argomenti vanno scritte dentro la funzione.

Posso chiamare una Server Action da un altro servizio?

No, non in modo stabile: l'endpoint generato non è un contratto pubblico. Per un servizio esterno serve una route API.

Le Server Actions funzionano su hosting statico?

No, serve un server che le esegua. Su un sito statico la mutazione passa da una route API esterna o da un servizio dedicato.

Come si gestisce l'errore in una Server Action?

Restituendo un oggetto con lo stato e il messaggio, non lanciando: l'eccezione arriva al client come errore generico in produzione.

Si possono usare con React senza Next.js?

Non ancora in modo stabile: il supporto è legato al bundler e al framework. Fuori da Next conviene una route API.