Type safety seems challenging. Since endpoints return Response objects, I don't think their body type can be easily retrieved. Tools like nuxt (through nitro through h3), trpc or remix either require returning objects or use helper functions

Ecosystem solutions

There are a variety of solutions to handling form / server actions throughout the JS ecosystem. Let's discuss the design of each, understand their goals, and see what aspects we could bring to an Astro solution.

Remix

Remix was among the first JS frameworks to make "actions" a primitive. Actions are defined at the route or layout level using by exporting an action() function. This receives the request with FormData for any form submitted using the Remix Form component. The action can trigger redirects or return data accessible in React from the useActionData() hook.

import type { ActionFunctionArgs } from "@remix-run/node";
import { redirect } from "@remix-run/node";
import { Form } from "@remix-run/react";
import { fakeCreateTodo } from "~/utils/db";

export async function action({
  request,
}: ActionFunctionArgs) {
  const body = await request.formData();
  const todo = await fakeCreateTodo({
    title: body.get("title"),
  });
  return redirect(`/todos/${todo.id}`);
}

export default function Todos() {
  return (
    <Form method="post">
      <input type="text" name="title" />
      <button type="submit">Create Todo</button>
    </Form>
  );
}

This offers clear wins for colocation and embracing browser standards. However, there are drawbacks to mirroring the API in Astro:

1. Actions can be shared across pages with nested routing. Server logic often needs to be called from multiple related pages. Since Astro does not have nested routing, we would require users to copy related action code across all routes manually.
2. Handling multiple forms on a page is left to the user. Each route has exactly one action handler. When multiple forms are present, the user must add a hidden input field with the form name and set conditionals manually. This is a rough edge for Astro's userbase that's less familiar with server rendering.
3. Response values are not type-safe. The result of an action is retrieved with the useActionData() hook. For type safety, the user must add a generic: useActionData<typeof action>(). A type cast also does not guarantee the type is correct, in case useActionData() is called from a route expecting a different action.
4. Actions must always be called from a form POST. As shown in our JSON endpoint example, programmatic calls from button presses are a common need. They are especially common for Astro SSG users that would prefer an isolated JSON endpoint, instead of server-rendering potentially thousands of content pages. As the Remix team explores server components and (potentially) server actions, it's possible they may break out from the API as well.

SvelteKit

SvelteKit follows Remix's approach pretty closely. Routes and layouts can define an actions object from a .server.ts file. This object can handle plain form requests using the default key, or handle requests for a specific form name using a named key. To set the form name, you can provide the property action="?name" to any form element.

This solves handling for multiple forms on a single page. SvelteKit also uses type generation for action results using a ./$types file, which solves Remix's type casting issue. However, problems (1) and (4) from our Remix drawbacks still remain. It is solution to actions built around different design constraints: nested routing and a high tolerance for ./$magic.

React server actions

Server actions are the most recent take on forms from the JS community. Unlike Remix or SvelteKit, which use REST endpoints called by URL, server actions use remote procedure calls (RPCs) to call server-side functions directly from client code. This is possible with the "use server" decorator, which bundlers use to replace server code with a fetch() call in your client components.

// app/actions.ts
export async function addToCart(formData: FormData) {
  "use server";
  const name = formData.get('name');
  const quantity = formData.get('quantity');
  await db.insert('product').values({ userId, quantity, name });
}

// app/page.tsx
import { addToCart } from './actions';

export default async function Page() {
  // Apply as server form action
  return (
    <form action={addToCart}>
      <input type="hidden" name="name" value="flip-flops" />
      <input type="number" name="quantity" />
    </form>
  )
}

// app/CheckoutButton.tsx
"use client";
import { addToCart } from './actions';

function CheckoutButton() {
  // Call from client code
  return <button onClick={() => addToCart(/* form data */)}>Check out</button>
}

Server actions are the most flexible solution in the JS ecosystem today. Actions can be declared in any file, and frameworks like Next.js will auto-generate an endpoint whenever their bundler finds an action. This is great for library authors, who can add endpoints to any Next.js project by exporting functions with "use server".

The "use server" convention is also gaining adoption outside of Next.js, appearing in the latest SolidStart release and gaining interest from other React frameworks like Redwood and Remix.

However, that flexibility comes with tradeoffs:

Forgetting the "use server" decorator means server code will be bundled into the client. This is a severe punishment for forgetting a bundler flag. What's more, it's hard for a bundler to warn when a user forgets this flag. Server actions can be declared in any file, and a server action without "use server" is just... a function. For safety, users must ruthlessly flag server-only code, and frameworks must blacklist common server modules like astro:db NodeJS libraries.

Server actions generate endpoint paths. Generated endpoints are part of an action's power, but it's a double-edged sword for debugging. If a server action fails, server logs will can only include the generated endpoint name and stacktrace info. It is tough to track down a failing action in your codebase, and doubly tough for multiple server actions with the same function name. File-based routing solutions do not have this problem.

Last, server actions can be declared within a function closure. This has caused trouble in the Next.js community. Take the following "add to cart" example that authenticates the user with Clerk:

import { auth } from '@clerk/nextjs';
import { db } from 'not/astro/db';

export async function Dashboard() {
  const user = await auth();

  async function addToCart(formData: FormData) {
    "use server";
    const userId = user.id;
    const name = formData.get('name');
    const quantity = formData.get('quantity');
    await db.insert('product').values({ userId, quantity, name });
  }
  return (
    <form action={addToCart}>
      <input type="hidden" name="name" value="flip-flops" />
      <input type="number" name="quantity" />
    </form>
  )
}

Note that user is retrieved from a server component, and passed to the server action with a closure. It may seem that Dashboard will re-render server-side to get the latest user, then add the product to cart using a server action. But this is not the case; actions do not trigger component rerenders. Here, Next.js will discover user is required by the closure, and embed the user into the form as a hidden input to "resume" on later calls. All props are hashed to avoid leaking server information. Still, forgetting a second auth() check from the server action means you can now add to any user's cart. Devs likely won't forget the auth check in a standalone route handler. But with access to server variables via closures, bugs are far more subtle.

Astro could adopt "use server" while disallowing usage in closures. However, "use server" is not a framework-specific feature; it's a bundler spec with adoption in the wider React and (now) SolidJS ecosystems. If Astro adopts this spec, it should be adopted in full for compatibility. Between the security vulnerabilities and risks of bundling server code, it's hard to justify implementing "use server" as-is.

Import attributes

Several Astro core members have considered import attributes for safely calling server actions from client code. This stage 3 proposal introduces metadata attributes for any import using a with clause. The type field is included to enforce the MIME type to safely import non-js extensions, including type: 'json' for .json files and type: 'css' to parse .css files. It may be possible to extend import attributes for actions using a custom type: 'action':

import { addToCart } from './actions' with { type: 'action' };

This addresses a major concern with "use server": actions can no longer be declared from closures. However, bundler concerns still remain. Endpoint names would still be generated with this model, and forgetting the import attribute would bundle server code into the client. The latter is even more risky with this model, since the user must remember an import attribute at every callsite for a given action.

What's more, it's unclear if import attributes are meant to transform a file's contents. The import attributes proposal focuses on enforcing MIME types when importing non-JS extensions. Astro would be the first tool to bring import attributes to the bundler. Even if attributes can be used as a bundler hint, Vite has yet to support import attributes.

Astro excels at finding new solutions grounded in the web platform. But betting on a stage 3 proposal that does not have our use case in mind is a risk. In fact, "use server" is a better use of platform standards, as it follows the "use strict" convention to define how a JavaScript file is parsed.

Where to go from here

Of course, there is no "perfect" solution. Though from the drawbacks for each solution above, we can move forward with a stronger Astro proposal. For now, I want to leave room for discussion before presenting solutions myself. Open to your thoughts!