Astro Modules Reference

Purpose and Scope

Astro exposes several public capabilities through virtual modules: import specifiers such as astro:actions, astro:assets, and astro:transitions that are resolved by Astro instead of by files in an application project. This page helps maintainers and framework contributors reason about that module surface as a set of contracts rather than as isolated helpers. The source evidence here is deepest for astro:actions, so the page uses Actions as the detailed model for how a virtual module can split client behavior, server behavior, shared types, error serialization, and runtime dispatch while still presenting one stable import path to application authors.

Official documentation describes astro:actions as the module for building a type-safe backend callable from client code and HTML forms. It also documents astro:assets as the module for image, picture, font, and image-service helpers, and astro:transitions as the module for the client router and transition animation helpers. In practice, these modules form a public API layer above Astro internals: project code imports named exports, while the build and runtime decide which implementation is safe in a given environment. That distinction matters when adding exports, changing types, or debugging behavior that differs between browser calls and server calls.

The Actions runtime is a useful reference pattern because it deliberately separates shared client-safe utilities from server-only execution. The client entrypoint can create a proxy that serializes input and performs a fetch, while the server entrypoint can create a proxy that looks up the action in the current pipeline and invokes it against an Astro context. Both entrypoints re-export the same public type names and error helpers, allowing the virtual module to keep a coherent developer experience while still enforcing environment boundaries at runtime.

Sources: packages/astro/src/actions/runtime/client.ts, packages/astro/src/actions/runtime/entrypoints/client.ts, packages/astro/src/actions/runtime/entrypoints/server.ts, packages/astro/src/actions/runtime/server.ts, packages/astro/src/actions/runtime/types.ts

Relevant Source Files

• packages/astro/src/actions/runtime/client.ts - shared, client-safe Actions helpers, including ActionError, ActionInputError, error type guards, status-code mapping, action path helpers, proxy creation, and result deserialization support.
• packages/astro/src/actions/runtime/entrypoints/client.ts - browser-facing astro:actions entrypoint that exports client-safe names, throws for server-only utilities, serializes request bodies, attaches internal fetch headers, posts to the action route, and deserializes action results.
• packages/astro/src/actions/runtime/entrypoints/server.ts - server-facing astro:actions entrypoint that exports server-capable utilities and resolves actions through the current pipeline when actions are called from server code with an Astro context.
• packages/astro/src/actions/runtime/server.ts - server implementation of defineAction(), form and JSON input parsing, Zod validation, safe result handling, body reading, action lookup, and serialized response generation.
• packages/astro/src/actions/runtime/types.ts - public and internal Actions type contracts, including ActionClient, ActionHandler, ActionInputSchema, ActionAPIContext, SafeResult, SerializedActionResult, and ActionErrorCode.
• .github/workflows/build-sandbox-image.yml - CI workflow for building and publishing the repository sandbox image used by automation around the project, included here as the relevant operational signal in the requested source set.

Module Families and Public Contracts

A virtual module reference should first identify what code authors import, then explain which runtime owns the behavior. In the official module family, astro:actions is for type-safe server functions callable from browsers, forms, and server code. astro:assets provides components and utilities such as Image, Picture, Font, getImage, inferRemoteSize, getConfiguredImageService, and configuration data for optimized assets. astro:transitions provides the ClientRouter component plus animation helpers such as fade and slide. Other Astro module families, including content, environment variables, middleware, and i18n, follow the same broad idea: application code imports stable names, while Astro supplies environment-aware implementations.

The Actions source shows why this layer is more than a convenience export. The shared client-safe file defines ActionError and maps application-level error codes such as BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, and INTERNAL_SERVER_ERROR to HTTP statuses. It also exposes predicates that let user code distinguish normal action errors from input validation errors. That gives the virtual module a typed error vocabulary independent of the transport mechanism. Whether the call came from a browser fetch, a form submission, or a server-side invocation, user code can rely on a SafeResult shape and the same narrowing helpers.

Sources: packages/astro/src/actions/runtime/client.ts, packages/astro/src/actions/runtime/types.ts

The type layer defines the developer-facing contract for actions. ActionAccept is the accepted input transport mode, currently form or json. ActionHandler receives parsed input and an ActionAPIContext; ActionReturnType extracts a handler’s awaited return type; ActionInputSchema preserves a Zod schema for inference; and SafeResult is a discriminated result where either data is present and error is undefined, or error is present and data is undefined. ActionAPIContext is intentionally a Pick of Astro’s public API context, exposing request, URL, locals, cookies, routing, locale, session, cache, CSP, and logger capabilities to action handlers without requiring the complete rendering context.

Sources: packages/astro/src/actions/runtime/types.ts

astro:actions Compact Reference

Export or type	Contract	Source-backed behavior
defineAction({ accept, input, handler })	Defines an action from server code.	Selects a form or JSON server handler, validates with Zod when an input schema exists, and returns an action client function with safe and throwing call modes.
actions	Proxy object for calling declared actions.	Client entrypoint posts serialized input to an action route; server entrypoint resolves the action from the current pipeline.
getActionPath	Builds an action URL/path.	Created with import.meta.env.BASE_URL and the configured trailing-slash behavior.
getActionContext	Server-only utility.	Exported from the server entrypoint; the client entrypoint throws if it is called in the browser.
ActionError	Serializable action failure.	Stores an Astro action error type, code, and mapped HTTP status.
ActionInputError	Validation-specific action failure.	Carries Zod issues and field-level error information without exposing the full Zod error object to the client.
isActionError()	Type guard.	Checks for the serialized Astro action error marker.
isInputError()	Type guard.	Narrows action errors with issue arrays to input validation errors.
ACTION_QUERY_PARAMS	Routing constant.	Re-exported by both client and server entrypoints.
ActionClient	Callable action type.	Returns Promise<SafeResult<...>> by default and includes orThrow() for throwing semantics.

The most important authoring distinction is between safe calls and throwing calls. A generated action client normally resolves to SafeResult, which encourages UI code to handle validation and server failures without try/catch. The same action also has an orThrow() method for code paths where exceptions are preferred. The server implementation attaches that method to the server handler returned by defineAction(), while the type definition models it as part of ActionClient. This keeps the ergonomics of calling an action aligned with the runtime behavior that actually executes the handler.

Sources: packages/astro/src/actions/runtime/server.ts, packages/astro/src/actions/runtime/types.ts

Client and Server Execution Flow

On the browser side, the astro:actions entrypoint protects developers from accidentally using server-only APIs. defineAction() and getActionContext() throw immediately if they are imported into client code and called. The exported actions proxy instead accepts a parameter and an action path, prepares request headers, applies adapter-specific internal fetch headers, serializes non-FormData input as JSON, and posts to the action URL. If JSON serialization fails, the client raises an ActionError with BAD_REQUEST; if the response is empty, successful, or an error, it converts the HTTP response into a serialized action result and then deserializes it for the caller.

Sources: packages/astro/src/actions/runtime/entrypoints/client.ts

On the server side, the astro:actions entrypoint can call actions without going through browser transport, but only when it has an Astro context carrying the internal pipeline symbol. The proxy extracts the pipeline from the context, fails with Astro’s action-called-from-server error when the context is invalid, looks up the action by path, and binds the action to the current context before invoking it. This design makes server-to-server action calls explicit: they are not arbitrary function imports, but context-bound calls that participate in the same routing and pipeline model as the rest of Astro’s runtime.

Sources: packages/astro/src/actions/runtime/entrypoints/server.ts

Inside the server implementation, defineAction() chooses a handler wrapper based on the accept option. Form actions require FormData, can parse object-like form data through a Zod schema, and throw ActionInputError when validation fails. JSON actions reject FormData, parse unknown input through Zod when a schema exists, and otherwise pass the unparsed input to the handler. Returned values are serialized with devalue, matching the official documentation’s guarantee that values beyond plain JSON, such as dates and maps, can be transported when supported by that serializer.

Sources: packages/astro/src/actions/runtime/server.ts

Error, Serialization, and Type Inference Details

The Actions error model ties together HTTP semantics, runtime serialization, and TypeScript inference. codeToStatusMap is implemented from the IANA HTTP status code registry and gives ActionErrorCode its key space through the type file. The reverse status-to-code map lets a response status become an action error code, with INTERNAL_SERVER_ERROR as the fallback. ActionError.fromJson() reconstructs an input error when the payload has input issues, reconstructs a general action error when the action error marker is present, and otherwise produces an internal-server-error action error. This keeps unknown or malformed failures from leaking transport details into user code.

Sources: packages/astro/src/actions/runtime/client.ts, packages/astro/src/actions/runtime/types.ts

Input errors get special treatment because form and JSON validation should be easy to display in interfaces. ActionInputError deliberately exposes issues and fields rather than the full Zod error object, because not every Zod property serializes cleanly and because importing the complete Zod error shape into the client would enlarge the public client surface. The type file preserves the schema in an internal inference key so that, after isInputError(result.error), a field such as name can be understood as part of the validated input shape. That is the kind of detail module references should record: the runtime constraint and the type-level developer benefit are connected.

Sources: packages/astro/src/actions/runtime/client.ts, packages/astro/src/actions/runtime/types.ts

The ActionAPIContext type also shows the boundary Astro wants action handlers to use. It includes request information, cookies, locals, sessions, cache, CSP, logger, route data, locale data, and deployment-related request properties, but it is not simply an unconstrained APIContext alias. For module authors, this matters because adding or removing context fields changes what server actions can depend on. For application authors, it explains why an action handler can read cookies, inspect route parameters, use locals, and access session or cache facilities while remaining separate from component rendering.

Sources: packages/astro/src/actions/runtime/types.ts

Operational and CI Signals

The requested source set also includes a sandbox image workflow. It is not part of the astro:* application import API, but it is relevant to repository operations around a large framework that exposes runtime modules. The workflow builds and pushes a flue-sandbox image to GitHub Container Registry on changes to the sandbox Dockerfile, sandbox agent instructions, or the workflow itself, and it can also run manually through workflow_dispatch. It lowercases the image name, checks out the repository, logs in to GHCR with the GitHub token, configures Docker Buildx, and publishes both a latest tag and a content-hash tag with GitHub Actions cache support.

Sources: .github/workflows/build-sandbox-image.yml

For module work, treat this as a signal that some contributor and automation workflows may execute in a controlled sandbox image rather than only in a local checkout. That does not change the public contract of astro:actions, astro:assets, or astro:transitions, but it does affect how maintainers should think about reproducibility when debugging runtime behavior. If a module change depends on environment-specific behavior, adapter-specific headers, request body limits, or serialization details, make the behavior explicit in source tests and avoid relying on local-only assumptions.

Sources: .github/workflows/build-sandbox-image.yml, packages/astro/src/actions/runtime/entrypoints/client.ts, packages/astro/src/actions/runtime/server.ts

Next Steps

When editing astro:actions, start from the public import contract and then follow the environment split. Add shared error or type changes in the client-safe and type files, add server execution behavior in the server runtime, and verify that both entrypoints still export the names documented for astro:actions. When documenting or reviewing other module families, use the same checklist: identify the import names, identify which exports are components, helpers, constants, or types, describe which environments may execute them, and call out any serialization, validation, routing, or adapter behavior that affects application code.

For adjacent reading, use the Actions page for guide-level examples, the API Reference for package-wide public exports, the Image Service Reference for asset pipeline details, and the View Transitions page for router and animation behavior. The key idea is that Astro modules are public contracts with runtime-aware implementations. Keeping those layers distinct makes the docs easier to trust and makes source changes safer to review.