Astro Container API (experimental)
Added in:
astro@4.9.0
The Container API allows you to render Astro components in isolation.
This experimental server-side API unlocks a variety of potential future uses, but is currently scoped to allow testing of .astro
component output in vite
environments such as vitest
.
It also allows you to manually load rendering scripts for creating containers in pages rendered on demand or other “shell” environments outside of vite
(e.g. inside a PHP or Elixir application).
This API allows you to create a new container, and render an Astro component returning a string or a Response
.
This API is experimental and subject to breaking changes, even in minor or patch releases. Please consult the Astro CHANGELOG for changes as they occur. This page will always be updated with the most current information for the latest version of Astro.
create()
Section titled create()Creates a new instance of the container.
It accepts an object with the following options:
streaming
option
Section titled streaming optionType: boolean
Enables rendering components using HTML streaming.
renderers
option
Section titled renderers optionType: AddServerRenderer[]
A list of loaded client renderers required by the component. Use this if your .astro
component renders any UI framework components or MDX using an official Astro integration (e.g. React, Vue, etc.).
Renderers can be added through the Container API automatically for static applications, or cases where the container isn’t called at runtime (e.g. testing with vitest
).
For on-demand rendered applications, or cases where the container is called at runtime or inside other “shells” (e.g. PHP, Ruby, Java, etc.), renderers must be manually imported.
Adding a renderer through the Container API
Section titled Adding a renderer through the Container APIFor each official Astro integration, import and use the getContainerRenderer()
helper function to expose its client and server rendering scripts. These are available for @astrojs/react
, @astrojs/preact
, @astrojs/solid-js
, @astrojs/svelte
, @astrojs/vue
, @astrojs/lit
, and @astrojs/mdx
.
For renderer packages outside the @astrojs
npm org, look in their documentation for getContainerRenderer()
or a similar function provided.
When using vite
(vitest
, Astro integrations, etc.), the renderers are loaded with the function loadRenderers()
from the virtual module astro:container
. Outside vite
, you’ll have to load the renderers manually.
The following example provides the necessary object to render an Astro component that renders a React component and a Svelte component:
Adding a renderer manually
Section titled Adding a renderer manuallyWhen the container is called at runtime, or inside other “shells”, the astro:container
virtual module’s helper functions are not available. Import the necessary server renderer manually and store it inside the container using experimental_Astro.Container.addServerRenderer
.
The following example manually imports the server renderers for React and Vue components, and MDX for .mdx
pages.
renderToString()
Section titled renderToString()This function renders a specified component inside a container. It takes an Astro component as an argument and it returns a string that represents the HTML/content rendered by the Astro component.
Under the hood, this function calls renderToResponse
and calls Response.text()
.
It also accepts an object as a second argument that can contain a number of options.
renderToResponse()
Section titled renderToResponse()It renders a component, and it returns a Response
object.
It also accepts an object as a second argument that can contain a number of options.
Rendering options
Section titled Rendering optionsBoth renderToResponse
and renderToString
accept an object as their second argument:
These optional values can be passed to the rendering function in order to provide additional information necessary for an Astro component to properly render.
slots
Section titled slotsType: Record<string, any>
;
An option to pass content to be rendered with <slots>
.
If your Astro component renders one default slot, pass an object with default
as the key:
If your component renders named slots, use the slot names as the object keys:
You can also render components in cascade:
props
option
Section titled props optionType: Record<string, unknown>
An option to pass properties for Astro components.
request
option
Section titled request optionType: Request
An option to pass a Request
with information about the path/URL the component will render.
Use this option when your component needs to read information like Astro.url
or Astro.request
.
You can also inject possible headers or cookies.
params
option
Section titled params optionType: Record<string, string | undefined>
;
An object to pass information about the path parameter to an Astro component responsible for generating dynamic routes.
Use this option when your component needs a value for Astro.params
in order to generate a single route dynamically.
locals
options
Section titled locals optionsType: App.Locals
An option to pass information from Astro.locals
for rendering your component.
Use this option to when your component needs information stored during the lifecycle of a request in order to render, such as logged in status.
routeType
option
Section titled routeType optionType: "page" | "endpoint"
An option available when using renderToResponse
to specify that you are rendering an endpoint:
To test your endpoint on methods such as POST
, PATCH
, etc., use the request
option to call the correct function: