Actions API Reference
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Hinzugefügt in:
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
Section titled Imports from astro:actionsdefineAction()
Section titled defineAction()
Hinzugefügt in:
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.
handler()
property
Section titled handler() propertyType: (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
Section titled input validatorType: 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'
Section titled Use with accept: 'form'If your action accepts form inputs, use the z.object()
validator to automatically parse form data to a typed object. The following validators are supported for form data fields:
- Inputs of type
number
can be validated usingz.number()
- Inputs of type
checkbox
can be validated usingz.boolean()
- Inputs of type
file
can be validated usingz.instanceof(File)
- Multiple inputs of the same
name
can be validated usingz.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:
isInputError()
Section titled isInputError()Type: (error?: unknown | ActionError) => boolean
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.
isInputError()
.
ActionError
Section titled ActionError
Hinzugefügt in:
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.
Hinzugefügt in:
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 actioninput
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 theContent-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
Section titled message
Hinzugefügt in:
astro@4.15.0
The message
property accepts a string. (e.g. “User must be logged in.“)