+
+Astro Actions allow you to define and call backend functions with type-safety. Actions perform data fetching, JSON parsing, and input validation for you. This can greatly reduce the amount of boilerplate needed compared to using an [API endpoint](/en/guides/endpoints/).
+
+Use actions instead of API endpoints for seamless communication between your client and server code and to:
+
+- Automatically validate JSON and form data inputs using [Zod validaton](https://zod.dev/?id=primitives).
+- Generate type-safe functions to call your backend from the client and even [from HTML form actions](#call-actions-from-an-html-form-action). No need for manual `fetch()` calls.
+- Standardize backend errors with the [`ActionError`](/en/reference/api-reference/#actionerror) object.
+
+## Basic usage
+
+Actions are defined in a `server` object exported from `src/actions/index.ts`:
+
+```ts title="src/actions/index.ts"
+import { defineAction } from 'astro:actions';
+import { z } from 'astro:schema';
+
+export const server = {
+ myAction: defineAction({ /* ... */ })
+}
+```
+
+Your actions are available as functions from the `astro:actions` module. Import `actions` and call them client-side within a [UI framework component](/en/guides/framework-components/), [a form POST request](#call-actions-from-an-html-form-action), or by using a `
+```
+
+### Write your first action
+
+Follow these steps to define an action and call it in a `script` tag in your Astro page.
+
+
+
+1. Create a `src/actions/index.ts` file and export a `server` object.
+
+ ```ts title="src/actions/index.ts"
+ export const server = {
+ // action declarations
+ }
+ ```
+
+2. Import the `defineAction()` utility from `astro:actions`, and the `z` object from `astro:schema`.
+
+ ```ts ins={1-2} title="src/actions/index.ts"
+ import { defineAction } from 'astro:actions';
+ import { z } from 'astro:schema';
+
+ export const server = {
+ // action declarations
+ }
+
+3. Use the `defineAction()` utility to define a `getGreeting` action. The `input` property will be used to validate input parameters with a [Zod](https://zod.dev) schema and the `handler()` function includes the backend logic to run on the server.
+
+ ```ts ins={5-12} title="src/actions/index.ts"
+ import { defineAction } from 'astro:actions';
+ import { z } from 'astro:schema';
+
+ export const server = {
+ getGreeting: defineAction({
+ input: z.object({
+ name: z.string(),
+ }),
+ handler: async (input) => {
+ return `Hello, ${input.name}!`
+ }
+ })
+ }
+ ```
+
+4. Create an Astro component with a button that will fetch a greeting using your `getGreeting` action when clicked.
+
+ ```astro title="src/pages/index.astro"
+ ---
+ ---
+
+
+
+
+ ```
+
+5. To use your action, import `actions` from `astro:actions` and then call `actions.getGreeting()` in the click handler. The `name` option will be sent to your action’s `handler()` on the server and, if there are no errors, the result will be available as the `data` property.
+
+ ```astro title="src/pages/index.astro" ins={7, 12-13}
+ ---
+ ---
+
+
+
+
+ ```
+
+
+
+See the full Actions API documentation for details on [`defineAction()`](/en/reference/api-reference/#defineaction) and its properties.
+
+## Organizing actions
+
+All actions in your project must be exported from the `server` object in the `src/actions/index.ts` file. You can define actions inline or you can move action definitions to separate files and import them. You can even group related functions in nested objects.
+
+For example, to colocate all of your user actions, you can create a `src/actions/user.ts` file and nest the definitions of both `getUser` and `createUser` inside a single `user` object.
+
+```ts
+// src/actions/user.ts
+import { defineAction } from 'astro:actions';
+
+export const user = {
+ getUser: defineAction(/* ... */),
+ createUser: defineAction(/* ... */),
+}
+```
+
+Then, you can import this `user` object into your `src/actions/index.ts` file and add it as a top-level key to the `server` object alongside any other actions:
+
+```ts title="src/actions/index.ts" ins={1,5}
+import { user } from './user';
+
+export const server = {
+ myAction: defineAction({ /* ... */ }),
+ user,
+}
+```
+
+Now, all of your user actions are callable from the `actions.user` object:
+
+- `actions.user.getUser()`
+- `actions.user.createUser()`
+
+
+## Handling returned data
+
+Actions return an object containing either `data` with the type-safe return value of your `handler()`, or an `error` with any backend errors. Errors may come from validation errors on the `input` property or thrown errors within the `handler()`.
+
+### Checking for errors
+
+It's best to check if an `error` is present before using the `data` property. This allows you to handle errors in advance and ensures `data` is defined without an `undefined` check.
+
+```ts
+const { data, error } = await actions.example();
+
+if (error) {
+ // handle error cases
+ return;
+}
+// use `data`
+```
+
+### Accessing `data` directly without an error check
+
+To skip error handling, for example while prototyping or using a library that will catch errors for you, use the `.orThrow()` property on your action call to throw errors instead of returning an `error`. This will return the action's `data` directly.
+
+This example calls a `likePost()` action that returns the updated number of likes as a `number` from the action `handler`:
+
+```ts ins="orThrow"
+const updatedLikes = await actions.likePost.orThrow({ postId: 'example' });
+// ^ type: number
+```
+
+### Handling backend errors in your action
+
+You can use the provided `ActionError` to throw an error from your action `handler()`, such as "not found" when a database entry is missing, or "unauthorized" when a user is not logged in. This has two main benefits over returning `undefined`:
+
+
+- You can set a status code like `404 - Not found` or `401 - Unauthorized`. This improves debugging errors in both development and in production by letting you see the status code of each request.
+
+- In your application code, all errors are passed to the `error` object on an action result. This avoids the need for `undefined` checks on data, and allows you to display targeted feedback to the user depending on what went wrong.
+
+#### Creating an `ActionError`
+
+To throw an error, import the `ActionError()` class from the `astro:actions` module. Pass it a human-readable status `code` (e.g. `"NOT_FOUND"` or `"BAD_REQUEST"`), and an optional `message` to provide further information about the error.
+
+This example throws an error from a `likePost` action when a user is not logged in, after checking a hypothetical "user-session" cookie for authentication:
+
+```ts title="src/actions/index.ts" ins=/ActionError(?= )/ ins={9-12}
+import { defineAction, ActionError } from "astro:actions";
+import { z } from "astro:schema";
+
+export const server = {
+ likePost: defineAction({
+ input: z.object({ postId: z.string() }),
+ handler: async (input, ctx) => {
+ if (!ctx.cookies.has('user-session')) {
+ throw new ActionError({
+ code: "UNAUTHORIZED",
+ message: "User must be logged in.",
+ });
+ }
+ // Otherwise, like the post
+ },
+ }),
+};
+```
+
+#### Handling an `ActionError`
+
+To handle this error, you can call the action from your application and check whether an `error` property is present. This property will be of type `ActionError` and will contain your `code` and `message`.
+
+In the following example, a `LikeButton.tsx` component calls the `likePost()` action when clicked. If an authentication error occurs, the `error.code` attribute is used to determine whether to display a login link:
+
+```tsx title=src/components/LikeButton.tsx ins="if (error.code === 'UNAUTHORIZED') setShowLogin(true);"
+import { actions } from 'astro:actions';
+import { useState } from 'preact/hooks';
+
+export function LikeButton({ postId }: { postId: string }) {
+ const [showLogin, setShowLogin] = useState(false);
+ return (
+ <>
+ {
+ showLogin && Log in to like a post.
+ }
+
+
+ )
+}
+```
+
+### Handling client redirects
+
+When calling actions from the client, you can integrate with a client-side library like `react-router`, or you can use Astro's [`navigate()` function](/en/guides/view-transitions/#trigger-navigation) to redirect to a new page when an action succeeds.
+
+This example navigates to the homepage after a `logout` action returns successfully:
+
+```tsx title=src/pages/LogoutButton.tsx {2,7-8}
+import { actions } from 'astro:actions';
+import { navigate } from 'astro:transitions/client';
+
+export function LogoutButton() {
+ return (
+
+ );
+}
+```
+
+## Accepting form data from an action
+
+Actions accept JSON data by default. To accept form data from an HTML form, set `accept: 'form'` in your `defineAction()` call:
+
+```ts title="src/actions/index.ts" ins={6}
+import { defineAction } from 'astro:actions';
+import { z } from 'astro:schema';
+
+export const server = {
+ comment: defineAction({
+ accept: 'form',
+ input: z.object(/* ... */),
+ handler: async (input) => { /* ... */ },
+ })
+}
+```
+
+### Validating form data
+
+Actions will parse submitted form data to an object, using the value of each input’s `name` attribute as the object keys. For example, a form containing `` will be parsed to an object like `{ search: 'user input' }`. Your action's `input` schema will be used to validate this object.
+
+To receive the raw `FormData` object in your action handler instead of a parsed object, omit the `input` property in your action definition.
+
+The following example shows a validated newsletter registration form that accepts a user's email and requires a "terms of service" agreement checkbox.
+
+
+
+1. Create an HTML form component with unique `name` attributes on each input:
+
+ ```astro title="src/components/Newsletter.astro" /name="\w+"/
+
+ ```
+
+2. Define a `newsletter` action to handle the submitted form. Validate the `email` field using the `z.string().email()` validator, and the `terms` checkbox using `z.boolean()`:
+
+ ```ts title="src/actions/index.ts" ins={5-12}
+ import { defineAction } from 'astro:actions';
+ import { z } from 'astro:schema';
+
+ export const server = {
+ newsletter: defineAction({
+ accept: 'form',
+ input: z.object({
+ email: z.string().email(),
+ terms: z.boolean(),
+ }),
+ handler: async ({ email, terms }) => { /* ... */ },
+ })
+ }
+ ```
+
+ See the [`input` API reference](/en/reference/api-reference/#input-validator) for all available form validators.
+
+3. Add a `
+ ```
+
+ See [“Call actions from an HTML form action”](#call-actions-from-an-html-form-action) for an alternative way to submit form data.
+
+
+
+### Displaying form input errors
+
+You can validate form inputs before submission using [native HTML form validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) like `required`, `type="email"`, and `pattern`. For more complex `input` validation on the backend, you can use the provided [`isInputError()`](/en/reference/api-reference/#isinputerror) utility function.
+
+To retrieve input errors, use the `isInputError()` utility to check whether an error was caused by invalid input. Input errors contain a `fields` object with messages for each input name that failed to validate. You can use these messages to prompt your user to correct their submission.
+
+The following example checks the error with `isInputError()`, then checks whether the error is in the email field, before finally creating a message from the errors. You can use JavaScript DOM manipulation or your preferred UI framework to display this message to users.
+
+```js /isInputError(?= )/ {5-12}
+import { actions, isInputError } from 'astro:actions';
+
+const form = document.querySelector('form');
+const formData = new FormData(form);
+const { error } = await actions.newsletter(formData);
+if (isInputError(error)) {
+ // Handle input errors.
+ if (error.fields.email) {
+ const message = error.fields.email.join(', ');
+ }
+}
+```
+
+## Call actions from an HTML form action
+
+:::note
+Pages must be on-demand rendered when calling actions using a form action. [Ensure prerendering is disabled on the page](/en/guides/server-side-rendering/#opting-out-of-pre-rendering-in-hybrid-mode) before using this API.
+:::
+
+You can enable zero-JS form submissions with standard attributes on any `
+```
+
+### Redirect on action success
+
+To navigate to a different page when an action is successful without client-side JavaScript, you can prepend a path in the `action` attribute.
+
+For example, `action={'/confirmation' + actions.newsletter}` will navigate to `/confirmation` when the `newsletter` action succeeds:
+
+```astro title="src/components/NewsletterSignup.astro" /action=\{[^\{\}]+\}/
+---
+import { actions } from 'astro:actions';
+---
+
+
+```
+
+#### Dynamic redirect on action success
+
+If you need to decide where to redirect to dynamically, you can use an action’s result on the server. A common example is creating a product record and redirecting to the new product's page, e.g. `/products/[id]`.
+
+For example, say you have a `createProduct` action that returns the generated product id:
+
+```ts title="src/actions/index.ts" mark={10}
+import { defineAction } from 'astro:actions';
+import { z } from 'astro:schema';
+
+export const server = {
+ createProduct: defineAction({
+ accept: 'form',
+ input: z.object({ /* ... */ }),
+ handler: async (input) => {
+ const product = await persistToDatabase(input);
+ return { id: product.id };
+ },
+ })
+}
+```
+
+You can retrieve the action result from your Astro component by calling `Astro.getActionResult()`. This returns an object containing `data` or `error` properties when an action is called, or `undefined` if the action was not called during this request.
+
+Use the `data` property to construct a URL to use with `Astro.redirect()`:
+
+```astro title="src/pages/products/create.astro" {4-7}
+---
+import { actions } from 'astro:actions';
+
+const result = Astro.getActionResult(actions.createProduct);
+if (result && !result.error) {
+ return Astro.redirect(`/products/${result.data.id}`);
+}
+---
+
+
+```
+
+### Handle form action errors
+
+Astro will not redirect to your `action` route when an action fails. Instead, the current page is reloaded with any errors the action returned. Calling `Astro.getActionResult()` in the Astro component containing your form gives you access to the `error` object for custom error handling.
+
+The following example displays a general failure message when a `newsletter` action fails:
+
+```astro title="src/pages/index.astro" {4,7-9}
+---
+import { actions } from 'astro:actions';
+
+const result = Astro.getActionResult(actions.newsletter);
+---
+
+{result?.error && (
+
Unable to sign up. Please try again later.
+)}
+
+```
+
+For more customization, you can [use the `isInputError()` utility](#displaying-form-input-errors) to check whether an error is caused by invalid input.
+
+The following example renders an error banner under the `email` input field when an invalid email is submitted:
+
+```astro title="src/pages/index.astro" ins={5,13} ins='aria-describedby="error"'
+---
+import { actions, isInputError } from 'astro:actions';
+
+const result = Astro.getActionResult(actions.newsletter);
+const inputErrors = isInputError(result?.error) ? result.error.fields : {};
+---
+
+
+```
+
+:::note
+Astro persists action `data` and `error` with a single-use cookie. This means `getActionResult()` will return a result on the first request _only_, and `undefined` when revisiting the page.
+:::
+
+#### Preserve input values on error
+
+Inputs will be cleared whenever a form is submitted. To persist input values, you can [enable view transitions](/en/guides/view-transitions/#adding-view-transitions-to-a-page) on the page and apply the `transition:persist` directive to each input:
+
+```astro ins="transition:persist"
+
+```
+
+### Update the UI with a form action result
+
+The result returned by `Astro.getActionResult()` is single-use, and will reset to `undefined` whenever the page is refreshed. This is ideal for [displaying input errors](#handle-form-action-errors) and showing temporary notifications to the user on success.
+
+:::tip
+If you need a result to be displayed across page refreshes, consider storing the result in a database or [in a cookie](/en/reference/api-reference/#astrocookies).
+:::
+
+Pass an action to `Astro.getActionResult()` and use the returned `data` property to render any temporary UI you want to display. This example uses the `productName` property returned by an `addToCart` action to show a success message:
+
+```astro title="src/pages/products/[slug].astro"
+---
+import { actions } from 'astro:actions';
+
+const result = Astro.getActionResult(actions.addToCart);
+---
+
+{result && !result.error && (
+
Added {result.data.productName} to cart
+)}
+
+
+```
+
+:::caution
+Action data is passed using a persisted cookie. **This cookie is not encrypted.** In general, we recommend returning the minimum information required from your action `handler` to avoid vulnerabilities, and persist other sensitive information in a database.
+
+For example, you might return the name of a product in an `addToCart` action, rather than returning the entire `product` object:
+
+```ts title="src/actions/index.ts" del={7} ins={8}
+import { defineAction } from 'astro:actions';
+
+export const server = {
+ addToCard: defineAction({
+ handler: async () => {
+ /* ... */
+ return product;
+ return { productName: product.name };
+ }
+ })
+}
+```
+:::
diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx
index 35dcff09e3cfd..9513bdf326bd3 100644
--- a/src/content/docs/en/reference/api-reference.mdx
+++ b/src/content/docs/en/reference/api-reference.mdx
@@ -764,6 +764,44 @@ This property is only available when building for SSR (server-side rendering) an
The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to `i18n.defaultLocale`.
+### `Astro.getActionResult()`
+
+
+
+`Astro.getActionResult()` is a function that returns the result of an [Action](/en/guides/actions/) submission. This accepts an action function as an argument (e.g. `actions.logout`) and returns a `data` or `error` object when a submission is received. Otherwise, it will return `undefined`.
+
+```astro title="src/pages/index.astro"
+---
+import { actions } from 'astro:actions';
+
+const result = Astro.getActionResult(actions.logout);
+---
+
+
+{result?.error &&
Failed to log out. Please try again.
}
+```
+
+### `Astro.callAction()`
+
+
+
+
+
+`Astro.callAction()` is a function used to call an Action handler directly from your Astro component. This function accepts an Action function as the first argument (e.g. `actions.logout`) and any input that action receives as the second argument. It returns the result of the action as a promise.
+
+```astro title="src/pages/index.astro"
+---
+import { actions } from 'astro:actions';
+
+const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
+---
+```
+
## Endpoint Context
[Endpoint functions](/en/guides/endpoints/) receive a context object as the first parameter. It mirrors many of the `Astro` global properties.
@@ -1028,6 +1066,42 @@ export function GET({ locals }: APIContext) {
See also: [`Astro.locals`](#astrolocals)
+### `context.getActionResult()`
+
+
+
+`context.getActionResult()` is a function that returns the result of an [Action](/en/guides/actions/) submission. This accepts an action function as an argument (e.g. `actions.logout`), and returns a `data` or `error` object when a submission is received. Otherwise, it will return `undefined`.
+
+
+See also [`Astro.getActionResult()`](#astrogetactionresult)
+
+### `context.callAction()`
+
+
+
+
+
+`context.callAction()` is a function used to call an Action handler directly from your Astro component. This function accepts an Action function as the first argument (e.g. `actions.logout`) and any input that action receives as the second argument. It returns the result of the action as a promise.
+
+
+See also [`Astro.callAction()`](#astrocallaction)
+
+## Endpoint Context
+
+[Endpoint functions](/en/guides/endpoints/) receive a context object as the first parameter. It mirrors many of the `Astro` global properties.
+
+```ts title="endpoint.json.ts"
+import type { APIContext } from 'astro';
+
+export function GET(context: APIContext) {
+ // ...
+}
+```
+
## `getStaticPaths()`
**Type:** `(options: GetStaticPathsOptions) => Promise | GetStaticPathsResult`
@@ -2075,6 +2149,118 @@ export const onRequest = defineMiddleware(async (context, next) => {
})
```
+## Actions (astro:actions)
+
+
+
+
+
+Actions are backend functions used for type-safe server-to-client communication. All utilities to define and call actions are exposed by the `astro:actions` module. For examples and usage instructions, [see the Actions guide](/en/guides/actions/).
+
+### `defineAction()`
+
+
+
+
+
+The `defineAction()` utility is used to define new actions from the `src/actions/index.ts` file. This accepts a `handler()` function containing the server logic to run, and an optional `input` property to validate input parameters at runtime.
+
+```ts
+export const server = {
+ getGreeting: defineAction({
+ input: z.object({
+ name: z.string(),
+ }),
+ handler: async (input) => {
+ return `Hello, ${input.name}!`
+ }
+ })
+}
+```
+
+#### `handler()` property
+
+
+
+
+
+`defineAction()` accepts a `handler()` function containing the server logic to run when the action is called. This function can return data that is automatically serialized and sent to the caller.
+
+Return values are parsed using the [devalue library](https://github.com/Rich-Harris/devalue). This supports JSON values, along with instances of `Date()`, `Map()`, `Set()`, or `URL()`.
+
+#### `input` validator
+
+
+
+
+
+The optional `input` property accepts a Zod validator to validate handler inputs at runtime. If the action fails to validate, [a `BAD_REQUEST` error](#actionerror) is returned and the `handler` is not called.
+
+If used with `accept: 'form'`, `input` must use the `z.object()` validator.
+
+Extension functions including `.refine()`, `.transform()`, and `.pipe()` are also supported on this object. The following validators are supported for form data fields:
+
+- Inputs of type `number` can be validated using `z.number()`
+- Inputs of type `checkbox` can be validated using `z.boolean()`
+- Inputs of type `file` can be validated using `z.instanceof(File)`
+- Multiple inputs of the same `name` can be validated using `z.array(/* validator */)`
+- All other inputs can be validated using `z.string()`
+
+### `isInputError()`
+
+
+
+The `isInputError()` utility is used to check whether an `ActionError` is an input validation error. When the `input` validator is a `z.object()`, input errors include a `fields` object with error messages grouped by name.
+
+See the [form input errors guide](/en/guides/actions/#displaying-form-input-errors) for more on using `isInputError()`.
+
+### `ActionError`
+
+
+
+
+
+The `ActionError()` constructor is used to create errors thrown by an action `handler`. This accepts a `code` property describing the error that occurred (example: `"UNAUTHORIZED"`), and an optional `message` property with further details.
+
+#### `code`
+
+
+
+
+
+The `code` property accepts human-readable versions of all HTTP status codes. The following codes are supported:
+
+- `BAD_REQUEST` (400): The client sent invalid input. This error is thrown when an action `input` validator fails to validate.
+- `UNAUTHORIZED` (401): The client lacks valid authentication credentials.
+- `FORBIDDEN` (403): The client is not authorized to access a resource.
+- `NOT_FOUND` (404): The server cannot find the requested resource.
+- `METHOD_NOT_SUPPORTED` (405): The server does not support the requested method.
+- `TIMEOUT` (408): The server timed out while processing the request.
+- `CONFLICT` (409): The server cannot update a resource due to a conflict.
+- `PRECONDITION_FAILED` (412): The server does not meet a precondition of the request.
+- `PAYLOAD_TOO_LARGE` (413): The server cannot process the request because the payload is too large.
+- `UNSUPPORTED_MEDIA_TYPE` (415): The server does not support the request's media type. Note: Actions already check [the `Content-Type` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) for JSON and form requests, so you likely won't need to raise this code manually.
+- `UNPROCESSABLE_CONTENT` (422): The server cannot process the request due to semantic errors.
+- `TOO_MANY_REQUESTS` (429): The server has exceeded a specified rate limit.
+- `CLIENT_CLOSED_REQUEST` (499): The client closed the request before the server could respond.
+- `INTERNAL_SERVER_ERROR` (500): The server failed unexpectedly.
+- `NOT_IMPLEMENTED` (501): The server does not support the requested feature.
+- `BAD_GATEWAY` (502): The server received an invalid response from an upstream server.
+- `SERVICE_UNAVAILABLE` (503): The server is temporarily unavailable.
+- `GATEWAY_TIMEOUT` (504): The server received a timeout from an upstream server.
+
+#### `message`
+
+
+
+
+
+The `message` property accepts a string. (e.g. "User must be logged in.")
+
## Built-in Components
Astro includes several built-in components for you to use in your projects. All built-in components are available in `.astro` files via `import {} from 'astro:components';`.
@@ -2332,4 +2518,4 @@ const serverObject = {
This component provides a way to inspect values on the client-side, without any JavaScript.
-[canonical]: https://en.wikipedia.org/wiki/Canonical_link_element
+[canonical]: https://en.wikipedia.org/wiki/Canonical_link_element
\ No newline at end of file
diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts
index a9a330d69dd3b..b938317e91bac 100644
--- a/src/i18n/en/nav.ts
+++ b/src/i18n/en/nav.ts
@@ -53,6 +53,7 @@ export default [
{ text: 'Routes and Navigation', header: true, type: 'learn', key: 'routes' },
{ text: 'Routing', slug: 'guides/routing', key: 'guides/routing' },
{ text: 'Endpoints', slug: 'guides/endpoints', key: 'guides/endpoints' },
+ { text: 'Actions', slug: 'guides/actions', key: 'guides/actions' },
{ text: 'Prefetch', slug: 'guides/prefetch', key: 'guides/prefetch' },
{ text: 'Middleware', slug: 'guides/middleware', key: 'guides/middleware' },
{