Actions API Reference

Agregado en: astro@4.15.0

Actions help you build a type-safe backend you can call from client code and HTML forms. All utilities to define and call actions are exposed by the astro:actions module. For examples and usage instructions, see the Actions guide.

Imports from astro:actions

import {
  actions,
  defineAction,
  isInputError,
  isActionError,
  ActionError,
 } from 'astro:actions';

defineAction()

Agregado en: astro@4.15.0

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.

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, context) => {
      return `Hello, ${input.name}!`
    }
  })
}

handler() property

Type: (input, context) => any

defineAction() requires a handler() function containing the server logic to run when the action is called. Data returned from the handler is automatically serialized and sent to the caller.

The handler() is called with user input as its first argument. If an input validator is set, the user input will be validated before being passed to the handler. The second argument is a context object containing most of Astro’s standard endpoint context, excluding getActionResult(), callAction(), and redirect().

Return values are parsed using the devalue library. This supports JSON values and instances of Date(), Map(), Set(), and URL().

input validator

Type: ZodType | undefined

The optional input property accepts a Zod validator (e.g. Zod object, Zod discriminated union) to validate handler inputs at runtime. If the action fails to validate, a BAD_REQUEST error is returned and the handler is not called.

If input is omitted, the handler will receive an input of type unknown for JSON requests and type FormData for form requests.

Use with accept: 'form'

If your action accepts form inputs, use the z.object() validator to automatically parse form data to a typed object. All Zod validators are supported for form data fields (e.g. z.coerce.date()). Astro additionally provides special handling under the hood for your convenience for validating the following types of field inputs:

• Inputs of type number can be validated using z.number()
• Inputs of type checkbox can be validated using z.coerce.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()

Extension functions including .refine(), .transform(), and .pipe() are also supported on the z.object() validator.

To apply a union of different validators, use the z.discriminatedUnion() wrapper to narrow the type based on a specific form field. This example accepts a form submission to either “create” or “update” a user, using the form field with the name type to determine which object to validate against:

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  changeUser: defineAction({
    accept: 'form',
    input: z.discriminatedUnion('type', [
      z.object({
        // Matches when the `type` field has the value `create`
        type: z.literal('create'),
        name: z.string(),
        email: z.string().email(),
      }),
      z.object({
        // Matches when the `type` field has the value `update`
        type: z.literal('update'),
        id: z.number(),
        name: z.string(),
        email: z.string().email(),
      }),
    ]),
    async handler(input) {
      if (input.type === 'create') {
        // input is { type: 'create', name: string, email: string }
      } else {
        // input is { type: 'update', id: number, name: string, email: string }
      }
    },
  }),
};

isInputError()

Type: (error?: unknown | ActionError) => boolean

Agregado en: astro@4.15.0

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 for more on using isInputError().

isActionError()

Type: (error?: unknown | ActionError) => boolean

Agregado en: astro@4.15.0

The isActionError() utility is used to check whether your action raised an ActionError within the handler property. This is useful when narrowing the type of a generic error in a try / catch block.

ActionError

Agregado en: astro@4.15.0

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

Agregado en: astro@4.15.0

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 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

Agregado en: astro@4.15.0

The message property accepts a string. (e.g. “User must be logged in.“)

getActionContext()

Type: (context: APIContext) => ActionMiddlewareContext

Agregado en: astro@5.0.0

getActionContext() is a function called from your middleware handler to retrieve information about inbound action requests.

This function returns an action object with information about the request, and the setActionResult() and serializeActionResult() functions to programmatically set the value returned by Astro.getActionResult().

getActionContext() lets you programmatically get and set action results using middleware, allowing you to persist action results from HTML forms, gate action requests with added security checks, and more.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});

action

Type: { calledFrom: 'rpc' | 'form', name: string, handler: () => Promise<SafeResult<any, any>> } | undefined

action is an object containing information about an inbound action request.

It is available from getActionContext(), and provides the action name, handler, and whether the action was called from an client-side RPC function (e.g. actions.newsletter()) or an HTML form action.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'rpc' && action.name.startsWith('private')) {
    // Check for a valid session token
  }
  // ...
});

setActionResult()

Type: (actionName: string, actionResult: SerializedActionResult) => void

setActionResult() is a function to programmatically set the value returned by Astro.getActionResult() in middleware. It is passed the action name and an action result serialized by serializeActionResult().

This is useful when calling actions from an HTML form to persist and load results from a session.

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';
export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    // ... handle the action result
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});

See the advanced sessions guide for a sample implementation using Netlify Blob.

serializeActionResult()

Type: (result: SafeResult<any, any>) => SerializedActionResult

serializeActionResult() will serialize an action result to JSON for persistence. This is required to properly handle non-JSON return values like Map or Date as well as the ActionError object.

Call this function when serializing an action result to be passed to setActionResult():

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { action, setActionResult, serializeActionResult } = getActionContext(context);
  if (action) {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  // ...
});

deserializeActionResult()

Type: (result: SerializedActionResult) => SafeResult<any, any>

deserializeActionResult() will reverse the effect of serializeActionResult() and return an action result to its original state. This is useful to access the data and error objects on a serialized action result.

getActionPath()

Type: (action: ActionClient<any, any, any>) => string

Agregado en: astro@5.1.0

The getActionPath() utility accepts an action and returns a URL path so you can execute an action call as a fetch() operation directly. This allows you to provide details such as custom headers when you call your action. Then, you can handle the custom-formatted returned data as needed, just as if you had called an action directly.

This example shows how to call a defined like action passing the Authorization header and the keepalive option:

src/components/my-component.astro

<script>
import { actions, getActionPath } from 'astro:actions'

await fetch(getActionPath(actions.like), {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({ id: 'YOUR_ID' }),
  keepalive: true
})
</script>

This example shows how to call the same like action using the sendBeacon API:

src/components/my-component.astro

<script>
import { actions, getActionPath } from 'astro:actions'

navigator.sendBeacon(
  getActionPath(actions.like),
  new Blob([JSON.stringify({ id: 'YOUR_ID' })], {
    type: 'application/json'
  })
)
</script>