action(): definir y disparar una mutación de servidor

Hasta ahora leíste el servidor: query y createAsync traían datos hacia la pantalla. Escribir es la otra mitad, y su primitiva es action. Una action envuelve una función asíncrona y le da algo que una función suelta no tiene: identidad. Esa identidad —una url estable— es lo que permite que el router rastree cada envío, empareje su estado con la UI y, cuando no hay JavaScript, sirva la mutación como un POST de verdad. Definir una action es tender un cable con nombre entre un evento del cliente y una escritura en el servidor.

Qué es una action y qué la parte en dos

Una action es una función asíncrona envuelta por action, con un "use server" en su cuerpo que marca la frontera de ejecución. Ese cierre es el corazón del modelo: el compilador de SolidStart corta la función en dos mitades. En el servidor queda el cuerpo real, con acceso a la base de datos, los secretos y el sistema de archivos. En el cliente queda un stub RPC —un sustituto diminuto que serializa sus argumentos, hace un POST a una url y devuelve una promesa con la respuesta—. Tú escribes una sola función; el framework la desdobla.

import { action } from "@solidjs/router";

const crearNota = action(async (form: FormData) => {
  "use server";
  const texto = String(form.get("texto") ?? "");
  if (!texto.trim()) throw new Error("La nota está vacía");
  await db.notas.crear({ texto });
}, "crearNota");

El segundo argumento, "crearNota", es el name, y no es decorativo: fija la propiedad .url con la que el router identifica la action de forma estable entre cliente y servidor. Sin nombre, el router deriva una url del módulo compilado; con nombre, tú controlas ese identificador —imprescindible para que el emparejamiento de envíos y el <form> apunten siempre al mismo sitio aunque el bundle cambie de hash—.

Ese corte tiene además una consecuencia de seguridad que conviene nombrar: el cuerpo de servidor nunca llega al bundle del cliente. Las credenciales de la base de datos, las claves de API, la lógica de autorización que escribas dentro del "use server" viven solo en el servidor; el cliente recibe la url y el código de serialización, nada más. Por eso una action es el lugar natural para lo sensible: la frontera que el compilador dibuja es también una frontera de confianza, y cruzarla exige una petición HTTP explícita que puedes vigilar.

Dispararla con useAction

La vía imperativa es useAction: le pasas la action y te devuelve un llamador ligado al router actual. Ese llamador acepta los argumentos de la action y retorna una promesa con su resultado, de modo que lo invocas desde un onClick, un efecto o cualquier manejador, y puedes esperar su resolución con await.

import { useAction } from "@solidjs/router";

function Editor() {
  const crear = useAction(crearNota);

  async function guardar() {
    const form = new FormData();
    form.set("texto", "Mi primera nota");
    await crear(form);            // dispara la mutacion y espera la respuesta
  }

  return <button onClick={guardar}>Guardar</button>;
}

useAction no es un mero atajo de crearNota(...): es lo que engancha el envío al router para que su estado sea observable —lo verás con useSubmission— y para que la revalidación de queries se dispare al terminar. Llamar a la action pelada por fuera del router pierde ese cableado. La regla es simple: para invocar en código, pasa siempre por useAction.

El valor que resuelve esa promesa es exactamente lo que la action retorna, de modo que puedes encadenar lógica de cliente tras la confirmación del servidor —cerrar un diálogo, limpiar el campo, mostrar un aviso—. Y useAction compone con .with(): si prefijas argumentos, el llamador que obtienes ya los lleva puestos y solo le entregas el resto. Entre la vía imperativa y la declarativa no hay jerarquía; eliges por el disparador: un <form> cuando la mutación nace de un envío, useAction cuando nace de cualquier otro evento de tu código.

Dispararla desde un <form>

La vía declarativa es entregar la action al atributo action de un <form> con method="post". El navegador —no tú— la invoca al enviar, pasándole los datos del formulario como argumento. No escribes ningún manejador de envío: la conexión entre el formulario y la mutación es el propio atributo.

function NuevaNota() {
  return (
    <form action={crearNota} method="post">
      <input name="texto" placeholder="Escribe una nota" />
      <button type="submit">Crear</button>
    </form>
  );
}

El method="post" es obligatorio: sin él, el navegador trataría el envío como una navegación GET y la action no se dispararía. Y como la action tiene una .url estable, ese <form> es un formulario HTML legítimo apuntando a un endpoint real —la semilla del progressive enhancement que estudiarás a continuación—.

No escribes un onSubmit, no llamas a preventDefault, no construyes el FormData a mano: el navegador hace todo eso y le entrega a la action los datos del formulario como argumento. Ese argumento será un FormData o un URLSearchParams según el enctype, un matiz que la próxima lección desmenuza. Lo esencial ahora es el cambio de rol: en la vía imperativa tú disparas la action; en la declarativa la dispara el navegador al enviar, y tu única declaración es el atributo action.

flowchart TD
DEF[action con use server dentro] --> URL[nombre fija una url estable]
URL --> STUB[el cliente guarda un stub rpc]
STUB --> V1[useAction dispara desde codigo]
STUB --> V2[form action dispara desde el markup]
V1 --> SRV[la mutacion corre en el servidor]
V2 --> SRV
style DEF fill:#89b4fa,color:#11111b
style URL fill:#f9e2af,color:#11111b
style SRV fill:#a6e3a1,color:#11111b

Prefijar argumentos con .with()

Una action recibe un único flujo de argumentos, pero a menudo necesitas fijar uno antes de que el formulario aporte el resto —el id de la fila que se borra, el usuario dueño del recurso—. Para eso está .with(), que devuelve otra action con los argumentos iniciales ya rellenados; los datos del formulario se añaden después de ellos.

const borrarNota = action(async (id: string, _form: FormData) => {
  "use server";
  await db.notas.borrar(id);
}, "borrarNota");

// En una fila: el id va prefijado, el FormData lo pone el navegador al enviar
<form action={borrarNota.with(nota.id)} method="post">
  <button type="submit">Borrar</button>
</form>