Form actions

[bholmesdev]

⚠️ This has been moved to stage 2. Leave any comments or discussion there.

Summary

This kicks off a discussion to handle form submissions both server-side and client-side.

Goals

• You can send either a JSON object or form data to a form action.
• You no longer need boilerplate to safely parse the request body based on the Content-Type.
• You no longer need boilerplate to retrieve form data values from the request body. The action should be able to enumerate expected input names, and the handler should be able to retrieve these values without a type cast. In other words, no more bangs ! or as string casts as in the example formData.get('expected')! as string.
• You can call an action using a standard HTML form element with the action property.
• You can use client JavaScript to call an action using scripts or islands. When doing so, data returned by the action is type-safe without type casting. Note: This should consider form handling in popular component frameworks, like the useActionState() and useFormStatus() hooks in React 19.
• You can declare actions as an endpoint to call from prerendered / static pages using the hybrid output.

Non-goals

• A solution to client-side validation. Validation is a major piece to forms with several community libraries to choose from (ex. react-hook-form). Astro may recommend standard HTML attributes for client validation including the required and type properties on an input.
• A hook to retrieve the return value of an action from Astro frontmatter. Action return values may be accessed from client JavaScript for optimistic updates. Otherwise, we expect actions to persist any state to a database to be retrieved manually from your Astro components.
• Declaring actions within .astro frontmatter. Frontmatter forms a function closure, which can lead to misuse of variables within an action handler. This challenge is shared by getStaticPaths() and it would be best to avoid repeating this pattern in future APIs.

Background & Motivation

Form submissions are a core building block of the web that Astro has yet to form an opinion on (pun intended).

So far, Astro has been rewarded for waiting on the platform and the Astro community to mature before designing a primitive. By waiting on view transitions, we found a SPA-like routing solution grounded in native APIs. By waiting on libSQL, we found a data storage solution for content sites and apps alike. Now, we've waited on other major frameworks to forge new paths with form actions. This includes Remix actions, SvelteKit actions, React server actions, and more.

At the same time, Astro just launched its database primitive: Astro DB. This is propelling the Astro community from static content to more dynamic use cases:

• A like button that updates a database counter
• A comments section that inserts a new comment behind an auth gateway
• A newsletter form that pings a third party mailing service

To meet our community where it's heading, Astro needs a form submission story.

The problem with existing solutions

Astro presents two solutions to handling form submissions with today's primitives. Though capable, these tools are either too primitive or present unacceptable tradeoffs for common use cases.

JSON API routes

JSON API routes allow developers to handle POST requests and return a JSON response to the client. Astro suggests this approach with a documentation recipe, demonstrating how to create an API route and handle the result from a Preact component.

However, REST endpoints are overly primitive for basic use cases. The developer is left to handle parse errors and API contracts themselves, without type safety on either side. To properly handle all error cases, this grows complex for even the simplest of forms:

REST boilerplate example

// src/api/board/[board]/card/[card].ts
import { db, Card, eq, and, desc } from "astro:db";
import type { APIContext } from "astro";

const POST = async ({params, request}: APIContext) => {
  if (!params.card || !params.board) {
    return new Response(
      JSON.stringify({ success: false, error: "Invalid board or card ID" }),
      { status: 400 }
    );
  }

  if (!request.headers.get("content-type")?.includes("application/x-www-form-urlencoded")) {
    return new Response(
      JSON.stringify({ success: false, error: "Must be a form request" }),
      { status: 400 }
    );
  }

  const body = await request.formData();
  const name = body.get("name");
  const description = body.get("description");
  if (typeof name !== "string" || typeof description !== "string") {
    return new Response(
      JSON.stringify({ success: false, error: "Invalid form data" }),
      { status: 400 }
    );
  }

  // Actual app logic starts here!
  const res = await db
    .update(Card)
    .set({ name, description })
    .where(
      and(eq(Card.boardId, params.board), eq(Card.id, params.card))
    );

  return new Response(
    JSON.stringify({ success: res.rowsAffected > 0 }),
    { status: res.rowsAffected > 0 ? 200 : 404 }
  );
}

The client should also guard against malformed response values. This is accomplished through runtime validation with Zod, or a type cast to the response the client expects. Managing this contract in both places leaves room for types to fall out-of-sync. The manual work of defining and casting types is also added complexity that the Astro docs avoid for beginner use cases.

What's more, there is no guidance to progressively enhance this form. By default, a browser will send the form data to the action field specified on the <form> element, and rerender the page with the action response. This default behavior is important to consider when a user submits a form before client JS has finished parsing, a common concern for poor internet connections.

However, we cannot apply our API route as the action. Since our API route returns JSON, the user would be greeted by a stringified JSON blob rather than the refreshed contents of the page. The developer would need to duplicate this API handler into the page frontmatter to return HTML with the refreshed content. This is added complexity that our docs understandably don't discuss.

View transition forms

View transitions for forms allow developers to handle a submission from Astro frontmatter and re-render the page with a SPA-like refresh.

---
const formData = await Astro.request.formData();
const likes = handleSubmission(formData);
---

<form method="POST">
  <button>Likes {likes}</button>
</form>

This avoids common pitfalls with MPA form submissions, including the "Confirm resubmission?" dialog a user may receive attempting to reload the page. This solution also progressively enhances based on the default form action handler.

However, handling submissions from the page's frontmatter is prohibitive for static sites that cannot afford to server-render every route. It also triggers unnecessary work when client-side update is contained. For example, clicking "Likes" in this example will re-render the blog post and remount all client components without the transition:persist decorator.

Last, the user is left to figure out common needs like optimistic UI updates and loading states. The user can attach event listeners for the view transition lifecycle, though we lack documentation on how to do so from popular client frameworks like React.

[florian-lefebvre]

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

[bholmesdev]

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!

[rossrobino]

This would be great! I really enjoy SvelteKit's, here's a half-baked idea

---
import { z, defineAction, Form } from "astro:action";

export const actions = {
	register: defineAction({
		schema: z.object({
			name: z.string(),
			email: z.string().email(),
		}),
		post: async ({ parsedData }) => {
			parsedData.name; // string
			parsedData.email; //string

			// task
			if (error) return { success: false };

			return { success: true, ...parsedData };
		},
	}),
};

const { register } = Astro.form;

register.post; // { error: ZodError } | { success: false } | { success: true, name: string, email: string }
---

<Form method="post" action="/register">
	<input type="text" name="name" />
	<input type="email" name="email" />
	<button>Submit</button>
</Form>

The Form component could have a prevent default and set a data-astro-loading attribute for a loading state, then do something similar to client side routing to show the result.

Excited to use this feature however it ends up!

[bholmesdev]

I really like where you're heading with this! I agree that "named" action handlers are a great SvelteKit feature. Also love using the action to map to a handler 1-1 for progressive enhancement.

However, I'm debating if zod validation should be an explicit goal. I'd love to find a solution that makes validation easy (even a no-brainer) to add, but not something every action handler needs to have. React server actions get this right with handlers just being functions, which you could "wrap" with a zod handler if you want.

Also, 👍 to data-astro-loading. Adding an attribute to toggle styles would be awesome to avoid manual client JS

[third774]

+1 to schema validation being optional/left to user for implementation so that folks can use something like Valibot instead of Zod if they wish.

[rossrobino]

Agreed, schema should be optional. In this case maybe if no schema was defined then parsedData would be undefined. Then you could just use the request instead like in SvelteKit.

Another idea to make it library independent, add a validate function in your astro.config. Then Astro can use it to validate with the action's schema. This would at least encourage users to validate consistently throughout actions. Something like this could be the default with zod if the user didn't provide anything:

import { defineConfig } from "astro/config";
import type { ZodObject } from "zod";

export default defineConfig({
	output: "server",
	validate: (schema: ZodObject) => {
		const parsed = schema.safeParse();

		if (!parsed.success) return parsed.error;
 
		return parsed.data;
	},
});

At this point, it might be easier to just write it within another function and import it in each action instead rather than abstracting.

[pilcrowonpaper]

My biggest issues with server actions in frameworks like Next.js and SolidStart, where you define a function that runs on the server that can be called from the client, are:

1. Leaking server-side data
2. Closures

Given those 2 points, I'd prefer an API similar to SvelteKit, where you rather define handlers for each route in a separate file:

// +page.server.ts

export actions = {
  default: async (request: Request) => {
    // ...
  }
}

So the idea I feel most comfortable right now is to allow users to define both .astro and .ts files with the same name. .astro will be for rendering pages and .ts will be handling server stuff. This aligns with how Astro currently works too - you use .ts for server endpoints. You just define the action handler in the .ts file and Astro will re-render the page using the corresponding .astro file when the handler returns. A quick idea might look something like this:

// pages/index.astro
---
---

<form method="post">
  <input name="message"/>
  <button>Send</button>
</form>

// pages/index.ts

// we could probably provide more high level APIs here
export async function actions(context: ActionContext) {
  const message = context.formData.get("message");
  // ...
}

I initially thought about using --- block in Astro files, but this still comes with closure issues. It also feels very awkward to define route route actions within a function (which is what --- pretty much is).

I could also see Astro allowing you to define regular POST functions if you don't want the extra fluff, but still allowing you to colocate your page and form actions.

As for input validation, I think this should be up to the dev. Or, at the very least, you should be able to opt-out of the Zod validation.

For error handling, it could be as simple as allowing the users to pass an error Map object from the handler function to .astro. And Astro could also automatically give you the previous values.

// pages/index.astro
---
---

<form method="post">
  <input name="message" value="{Astro.form.values.get("message")}"/>
  <p>{Astro.form.errors.get("message")}</p>
  <button>Send</button>
</form>

// pages/index.ts

// we could probably provide more high level APIs here
export async function actions(context: ActionContext) {
  const message = context.formData.get("message");
  // ...
  errors.set("message", "Message too long");
}

Astro could even export a framework-agnostic API to call APIs from the client.

import { submitForm } from "astro/client";

const formData = new FormData();
// populate FormData
const result = await submitForm(formData);
const error = result.errors.get("message");

[pilcrowonpaper]

If we're fine with type-gen, instead of a Map, we could allow devs to return a POJO from the action handler and Astro could infer the return type of the handler.

[guigui64]

We could be more explicit with pages/foo/index.astro (or pages/foo.astro) and pages/foo/actions.ts.

[lvindotexe]

i don't think colocation should be a big issue since astro is a server first framework, the only way to get info into the client is explicitly passing(serializable) props to client components. seperation would be nice but should not the default

[bholmesdev]

@liruifengv I agree that colocation with client code should not be a goal! In fact, I would consider server actions within a client module to be an anti-pattern (as would React).

[bholmesdev]

Thanks for sharing a detailed outline Pilcrow! Definitely agree with some ideas presented here:

• In general, named actions a-la SvelteKit are ergonomic.
• Actions should be colocated near Astro components, but not be exported within an Astro component. You're right that the --- establishes a closure, and this can lead to similar footguns to getStaticPaths().
• We should consider form errors as part of any form action design. Agree with your follow-up comment to allow the user to return error states with some sort of type inference, instead of a magic Astro.form.errors object. We are no strangers to codegen, so this should be possible.

I also agree with your thought that server actions a) cause closures and b) potentially leak server-side data. However, I'm playing with a design that could address those shortcomings without ruling out server actions completely. Will share more soon

[etmartinkazoo]

Thank you for your work on this @bholmesdev

I am a big fan of the Adonisjs framework and their library Vinejs for validation may be something to look at as it is open source and works on Nodejs. Perhaps it would offer some ideas/inspiration around implementations. Either way form story is the missing piece for me with Astro. Thank you!

[bholmesdev]

Thanks for the share! Looks like Vinejs has native form serialization, really interesting 👀